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

# Authentication

> OAuth for interactive chat clients, API keys for scripts. Both arrive at the MCP endpoint; both produce scoped, org-bound access.

The Orisu MCP endpoint accepts two auth modes. Both end up at the same set of tools. The only difference is how the bearer token is obtained.

<Snippet file="snippets/mcp-endpoints.mdx" />

## OAuth (chat clients)

When you add Orisu as a connector in Claude or ChatGPT, the host runs an OAuth flow against the Orisu web app. You sign in, see a consent screen listing the scopes the connector needs, approve, pick a workspace (if you have multiple), and the host now holds a refresh token. Every MCP call attaches a bearer token derived from it.

The flow:

1. Host fetches `/.well-known/oauth-authorization-server` from the API
2. Host dynamically registers itself as an OAuth client ([Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591))
3. Browser opens to the Orisu consent screen: you sign in (if needed) and approve scopes
4. Host receives an authorization code, exchanges it at the token endpoint
5. Host caches the access + refresh tokens; refreshes silently when access tokens expire

The first consent binds the connector to one of your workspaces. If you belong to multiple, you can rebind later by removing + re-adding the connector.

## API keys (scripts)

For server-to-server use (cron jobs, internal tooling, custom MCP hosts), generate an API key from your Orisu dashboard → **Settings → API Keys**. The key format is `pk_live_*`.

Send it as a Bearer token to the same endpoint:

```bash theme={null}
curl -X POST <YOUR_MCP_ENDPOINT> \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxx' \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
```

API keys carry a fixed scope set you choose at creation time. They never expire (revoke + reissue to rotate). Keys are bound to a single organization, so pick the right org when generating.

## Scopes

| Scope            | Allows                                                                                       |
| ---------------- | -------------------------------------------------------------------------------------------- |
| `agents:read`    | List agents, read graphs, validate specs, port resolution, model suggestions, cost estimates |
| `agents:write`   | Create / replace / update / clone / delete agents, restore versions, manage shares           |
| `runs:read`      | List runs, wait for runs, read `orisu://runs/{id}`                                           |
| `runs:execute`   | Trigger runs, cancel runs                                                                    |
| `apps:read`      | List apps, read app metadata                                                                 |
| `apps:execute`   | Trigger apps, publish apps, submit reviews                                                   |
| `assets:write`   | Upload assets via the connector                                                              |
| `openid`         | Required for OAuth flow (identity)                                                           |
| `offline_access` | Required for OAuth refresh tokens                                                            |

The OAuth consent screen requests the minimum scopes the connector needs to be useful. For API keys, only include the scopes the script actually needs. A read-only monitoring script doesn't need `agents:write` or `runs:execute`.

## Errors

If a tool needs a scope you don't have, the call fails with a typed error:

```json theme={null}
{
  "code": "SCOPE_MISSING",
  "message": "trigger_run requires 'runs:execute' but the bearer carries: agents:read, runs:read",
  "next_action": "Ask the user to reconnect Orisu and grant 'runs:execute', or use an Orisu API key (pk_live_*) whose scope set includes runs:execute."
}
```

See [Errors](/mcp/errors) for the full code list.

## See also

<Columns cols={2}>
  <Card title="Quickstart" icon="rocket" href="/mcp/quickstart">
    Add the connector to Claude or ChatGPT.
  </Card>

  <Card title="Errors" icon="circle-alert" href="/mcp/errors">
    Auth errors and how to recover from them.
  </Card>
</Columns>