# Investment Bets auth.md

This document describes the authentication model for agents and automated clients.

## Resource

- Web app: `https://investment-bets.com`
- API resource server: `https://api.investment-bets.com`

## Supported Authentication

Investment Bets currently uses first-party email/password accounts and JWT sessions stored in an HttpOnly cookie named `auth_token`.

OAuth, OIDC, dynamic client registration, bearer-token provisioning, and machine-to-machine API keys are not currently supported.

## Agent Audience and Registration

Agents and generated clients may read public discovery documents and public API endpoints without registration. Authenticated actions use a human user's first-party Investment Bets account.

There is no public agent registration endpoint, dynamic client registration endpoint, or automated credential provisioning endpoint at this time. Agents that need authenticated access should direct the human user through the normal account flow below, preserve the resulting HttpOnly cookie in their browser/session context, and avoid extracting or replaying cookie values outside that context.

The site publishes OAuth Protected Resource metadata at `https://investment-bets.com/.well-known/oauth-protected-resource` and `https://api.investment-bets.com/.well-known/oauth-protected-resource` so agents can discover that no OAuth authorization servers or OAuth scopes are currently advertised.

## Agent-Assisted Subscription Purchase

Agents may help an authenticated user compare and start paid subscription upgrades through Stripe, but the human user must explicitly authorize the billing action and complete Stripe Checkout themselves.

Recommended flow:

1. Read public plan data from `GET https://api.investment-bets.com/api/stripe/plans`.
2. Explain the plan name, price, billing interval, follow-slot increase, and open-bet capacity increase to the user.
3. Ask the user to explicitly choose a plan before calling any billing endpoint.
4. Create a Checkout Session with `POST https://api.investment-bets.com/api/stripe/checkout` and the selected `price_id`, using the user's authenticated cookie session.
5. Send the returned `url` to the browser or user for Stripe-hosted confirmation and payment entry.

Agents must not invent prices, auto-select paid plans without user confirmation, collect payment-card details directly, call Stripe webhooks, or treat a Checkout Session URL as proof of purchase. Subscription state changes only after Stripe webhook confirmation updates the user's account.

## Account Flow

1. Register with `POST https://api.investment-bets.com/register`. This only creates the account; it does not set a session cookie.
2. Log in with `POST https://api.investment-bets.com/login`.
3. Preserve cookies from the login response.
4. Send subsequent API requests with credentials/cookies included.
5. End the session with `POST https://api.investment-bets.com/logout`.

## Agent Rules

- Only create accounts, log in, open bets, close bets, follow users, manage billing, or link Telegram after explicit user instruction.
- Never ask users to paste the HttpOnly cookie.
- Do not call Stripe or Telegram webhook endpoints.
- For read-only discovery, prefer `/llms.txt`, `/openapi.json`, and `/.well-known/api-catalog`.

## Scopes

No OAuth scopes are defined. Authorization is based on the authenticated user session.