Authentication

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

API key

Use API keys for simple, persistent authentication in server environments. An API key is scoped to a single user and a single project, and its permissions are exactly that user’s permissions on that project. 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:

$
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:

$
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:

1
{
2
  "access_token": "ory_at_K5P_6Az5LWS28...",
3
  "token_type": "bearer",
4
  "expires_in": 3600,
5
  "scope": "offline_access"
6
}

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