> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.rightbrain.ai/v-1/docs/api/authentication/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.rightbrain.ai/_mcp/server.

# Authentication

> Authenticate with API keys, OAuth 2.0 client credentials, authorization code with PKCE, task access tokens, or public tasks.

Every Rightbrain API request is authenticated with an `Authorization: Bearer <token>` header. The token can be an API key, an OAuth 2.0 access token, or a task access token. Some tasks can be made public and called with no credential at all.

Organization and project are always taken from the URL path, not the token. A single credential resolves to your user, and your permissions are enforced per request against the project in the path.

Create and manage credentials under **Settings → API Clients** in your dashboard. The rest of this page is the API path.

## Which method to use

| Method                                    | Best for                                           | Token type               | Notes                                                       |
| ----------------------------------------- | -------------------------------------------------- | ------------------------ | ----------------------------------------------------------- |
| **API key**                               | Server-to-server automation, internal tools, CI/CD | Long-lived key           | Acts as its owning user; managed under a project; revocable |
| **OAuth 2.0 — client credentials**        | Service-to-service and multi-tenant backends       | Short-lived access token | Machine-to-machine, no user interaction                     |
| **OAuth 2.0 — authorization code / PKCE** | User-facing and client apps                        | Short-lived access token | Delegated access on behalf of a signed-in user              |
| **Task access token**                     | Sharing a single task with a third party           | Scoped access token      | Grants access to one task only                              |
| **Public task**                           | Open, unauthenticated task endpoints               | None                     | The task must be explicitly marked public                   |

> **Warning**
>
> Never expose API keys or client secrets in browser or other client-side code. For user-facing apps, use OAuth 2.0 authorization code with PKCE.

## API key

Use API keys for simple, persistent authentication in server environments. An API key is created and managed under a project, but authenticates as its owning user. Authorization is checked against the resource requested and that user’s permissions. Do not rely on the project where you created a key as an access-isolation boundary; use a dedicated user with access limited to the intended resources. Keys are stored encrypted at rest and can be revoked at any time — revoking a key immediately invalidates its tokens.

Create an API key under **Settings → API Clients** in your dashboard, copy it once (treat it like a password), then send it as a bearer token:

```bash
curl -X POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task/{task_id}/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_input": {"data": "Example input"}}'
```

Revoke a key via the API: `POST /api/v1/org/{org_id}/project/{project_id}/api_key/{id}/revoke`.

## OAuth 2.0 client

Use OAuth 2.0 when you need short-lived, revocable tokens — for distributed systems, multi-tenant backends, or apps acting on behalf of a signed-in user.

Create an OAuth client under **Settings → API Clients** in your dashboard, choosing a grant type — **client credentials** for server-to-server integrations, or **authorization code with PKCE** for user login and delegated access. Copy the **Client ID** and **Client Secret** (the secret is shown only once), then exchange them for a token as below.

### Client credentials flow

Exchange your client credentials for an access token at the token endpoint, then send that token as a bearer token.

Clients authenticate to the token endpoint with HTTP Basic auth — the client ID and secret in the `Authorization` header — which is the default for clients created in the dashboard:

```bash
curl -X POST https://oauth.rightbrain.ai/oauth2/token \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "scope=offline_access"
```

Response:

```json
{
  "access_token": "ory_at_K5P_6Az5LWS28...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "offline_access"
}
```

> **Note**
>
> OAuth tokens are short-lived by design. Cache the token and refresh it before `expires_in` elapses rather than requesting a new token per call.

### Authorization code with PKCE

For user-facing apps, use the authorization code grant with PKCE (Proof Key for Code Exchange). PKCE removes the need to embed a client secret in a public client such as a browser or mobile app.

1. Generate a random `code_verifier` and derive a `code_challenge` (`S256`).
2. Redirect the user to the authorization endpoint with `response_type=code`, your `client_id`, `redirect_uri`, `scope`, and the `code_challenge`.
3. After the user consents, exchange the returned `code` for tokens at `https://oauth.rightbrain.ai/oauth2/token` with `grant_type=authorization_code`, the `code`, your `redirect_uri`, and the original `code_verifier`.

Public clients require PKCE. The resulting access token acts on behalf of the signed-in user, with that user's permissions.

## Task access tokens

A task access token grants access to a single task rather than a whole project. Use it to let a third party run one specific task without giving them broader project access. Generate a task access token from the task's page in the dashboard, then use it as a bearer token against that task's `/run` endpoint.

## Public tasks

A task can be marked **public**, which makes its `/run` endpoint callable with no credential. When a task is public, the authorization check is skipped for run requests. Use this only for tasks whose input and output are safe to expose without authentication.

## Quick reference

| Use case                         | Recommended authentication            |
| -------------------------------- | ------------------------------------- |
| Internal automation or scripts   | API key                               |
| Backend microservices            | OAuth 2.0 (client credentials)        |
| User login or delegated access   | OAuth 2.0 (authorization code / PKCE) |
| Sharing a single task externally | Task access token                     |
| Open, unauthenticated endpoint   | Public task                           |

#### [Run tasks via the API](/docs/api/run-tasks)

Execute a task with REST, including file inputs and revision selection.

#### [Run agents via the API](/docs/api/run-agents)

Stream an agent run over Server-Sent Events.

> Build reliable AI agents that run inside your existing tools and workflows. Rightbrain developer documentation.