> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jogg.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and Scopes

> Understand JoggAI MCP OAuth, Space selection, resource-bound tokens, redirect URIs, and tool scopes.

JoggAI MCP uses OAuth 2.0 Authorization Code with PKCE. The browser flow
authenticates your JoggAI account, lets you select a Space, and asks you to
approve scopes before the client receives a token.

Public MCP access does not require copying a JoggAI API key into an agent.

## OAuth flow

<Steps>
  <Step title="Discover the protected resource">
    The client connects to `https://api.jogg.ai/mcp`. An unauthenticated
    response points it to JoggAI protected resource and authorization metadata.
  </Step>

  <Step title="Authorize the client">
    The client opens the JoggAI authorization page with PKCE `S256`,
    `resource=https://api.jogg.ai/mcp`, and its exact registered redirect URI.
  </Step>

  <Step title="Choose a Space and approve scopes">
    The selected Space determines which private resources are visible and which
    billing account generation tools use.
  </Step>

  <Step title="Receive a resource-bound token">
    The access token audience is `https://api.jogg.ai/mcp`. The client stores
    access and refresh tokens in its own credential store.
  </Step>
</Steps>

The `resource` value must remain identical during authorization, code exchange,
and refresh. A token issued for a JoggAI plugin or REST API has a different
audience and cannot be used with MCP.

## Discovery endpoints

| Metadata                   | URL                                                            |
| -------------------------- | -------------------------------------------------------------- |
| Protected resource         | `https://api.jogg.ai/.well-known/oauth-protected-resource`     |
| MCP path-specific metadata | `https://api.jogg.ai/.well-known/oauth-protected-resource/mcp` |
| OpenID configuration       | `https://api.jogg.ai/.well-known/openid-configuration`         |
| JSON Web Key Set           | `https://api.jogg.ai/.well-known/jwks.json`                    |

## Tool scopes

`tools/list` only returns tools allowed by the current token. JoggAI checks the
scope again on every `tools/call`.

| Scope             | Capability                                                       |
| ----------------- | ---------------------------------------------------------------- |
| `openid`          | Identify the authorized JoggAI user                              |
| `account.read`    | Read account information for the selected Space                  |
| `quota.read`      | Read the remaining quota of the actual billing account           |
| `catalog.read`    | List avatars, voices, music, templates, and visual styles        |
| `asset.read`      | Read authorized asset metadata when supported                    |
| `asset.write`     | Request signed asset uploads                                     |
| `script.generate` | Submit and inspect AI script jobs                                |
| `image.generate`  | Submit and inspect avatar image generation                       |
| `video.generate`  | Submit and inspect video, motion, lip sync, and translation jobs |
| `product.read`    | Read products, previews, and product results                     |
| `product.write`   | Create or update products                                        |
| `webhook.read`    | List webhook endpoints and supported events                      |
| `webhook.write`   | Create, update, or delete webhook endpoints                      |

<Note>
  Approving a scope makes matching tools discoverable; it does not bypass JoggAI
  Space membership, ownership, plan, quota, resource, or request validation.
</Note>

## Registered client redirects

JoggAI does not accept wildcard redirect URIs or arbitrary dynamic client
registration during controlled beta.

| Client         | Redirect behavior                                                     |
| -------------- | --------------------------------------------------------------------- |
| Codex          | Native loopback IP, dynamic port, and resource-specific callback path |
| Claude Code    | `http://localhost:5555/callback`                                      |
| Cursor desktop | `http://localhost:8787/callback`                                      |
| Cursor agents  | `https://www.cursor.com/agents/mcp/oauth/callback`                    |
| ChatGPT        | `https://chatgpt.com/connector_platform_oauth_redirect`               |

Codex should choose its own loopback port and path. Do not override it with
`localhost`, a private devbox hostname, or a custom HTTPS callback.

## Authorization errors

* `401 Unauthorized`: credentials are missing, invalid, expired, revoked, or
  bound to the wrong resource. Run the client's login flow again.
* `403 Forbidden`: authentication succeeded but the required scope or Space
  permission is missing. Reauthorize only if that permission should be granted.
* Redirect mismatch: the client sent a callback that was not registered exactly.
  Confirm the client and deployment configuration before retrying.

Never send access tokens, refresh tokens, authorization codes, API keys, or
signed upload URLs to support.