# auth.md

BubblaV lets a person use their own LLM agent to sign up for BubblaV and buy the Pro plan. The agent registers an OAuth client, the person signs in or creates an account and approves access, and the agent receives a scoped API key. The agent then uses that key for the BubblaV MCP server and for the ACP checkout API that sells the Pro plan.

## Audience

This document is for AI agents that act for a person who wants to sign up for BubblaV (bubblav.com) and buy a plan. The person may not have an account yet.

## Registration

| Item | Value |
|---|---|
| Registration endpoint (RFC 7591 DCR) | `POST https://www.bubblav.com/api/oauth/register` |
| Registration authentication | None. Registration creates an OAuth client only. |
| Claim (user approval) | `https://www.bubblav.com/oauth/authorize` |
| Token endpoint | `POST https://www.bubblav.com/api/oauth/token` |

## Supported Methods

- **Anonymous registration with user claim.** The agent registers a public OAuth client without credentials. The client gets no access token until the person claims it: at the claim URL they sign in or create a BubblaV account, add a website if the account has none, choose Full access or Read only, and approve. The agent then exchanges the authorization code (PKCE `S256`) for a credential. The `redirect_uri` must be on the BubblaV allowlist of known LLM clients.

No other method is supported. ID-JAG and verified-email assertions are not accepted.

## Buying the Pro plan

With a Full access key, call the ACP checkout API. Discovery: `https://www.bubblav.com/.well-known/acp.json`. Create a checkout session for item `pro_monthly` or `pro_yearly` with `POST https://www.bubblav.com/api/acp/checkout_sessions` and `Authorization: Bearer <key>`. The session contains a BubblaV hosted payment link. The person opens it and pays there. BubblaV does not accept payment tokens from agents.

## Credentials

- Credential type: `api_key`. The `access_token` returned by the token endpoint is a scoped MCP API key.
- Send it as `Authorization: Bearer <key>` or `X-API-Key: <key>`.
- Keys do not expire. The user revokes a key under **Settings → API Keys** in the dashboard.

## Authentication

1. **Register** as an OAuth client at the DCR endpoint
2. **Authorize** via the OAuth authorization endpoint (user signs in)
3. **Exchange** the authorization code for an access token (which is an MCP API key)
4. **Call** the MCP API using the API key

## Endpoints

| Endpoint | URL |
|---|---|
| Protected Resource Metadata | https://www.bubblav.com/.well-known/oauth-protected-resource |
| Authorization Server | https://www.bubblav.com/.well-known/oauth-authorization-server |
| Dynamic Client Registration | https://www.bubblav.com/api/oauth/register |
| Authorization | https://www.bubblav.com/oauth/authorize |
| Token Exchange | https://www.bubblav.com/api/oauth/token |
| MCP Server | https://www.bubblav.com/mcp |

## Using the API Key

Once you have an API key, call the MCP server:

```http
POST https://www.bubblav.com/mcp
Content-Type: application/json
X-API-Key: <your-api-key>

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}
```

Or with Bearer token:

```http
POST https://www.bubblav.com/mcp
Authorization: Bearer <your-api-key>
```

## Supported Scopes

| Scope | Description |
|---|---|
| `claudeai` | Claude AI integration access |
| `mcp:read` | Read access to MCP resources |
| `mcp:tools:execute` | Execute MCP tools on behalf of the user |

## Quick Start

Agents connecting via Claude Desktop or ChatGPT OAuth connector:
1. Register a client at the DCR endpoint
2. Send the person to the claim URL to sign up or sign in and approve
3. Exchange the code for the API key
4. Create an ACP checkout session for the Pro plan and give the payment link to the person