OAuth 2.1 for Developers

Barrd implements OAuth 2.1 with PKCE for MCP clients and third-party integrations. This page covers the authorization flow, scope system, and client registration.

Discovery

Barrd publishes OAuth metadata at standard endpoints:

GET /.well-known/oauth-authorization-server — server metadata (RFC 8414)
GET /.well-known/oauth-protected-resource — protected resource metadata (RFC 9728)

These return the authorization endpoint, token endpoint, supported scopes, and other details your client needs.

Registering a client

Dynamic registration

If enabled, clients can self-register via RFC 7591:

POST /oauth/register
Content-Type: application/json

{
  "client_name": "My MCP Client",
  "redirect_uris": ["http://localhost:8080/callback"],
  "grant_types": ["authorization_code"],
  "scope": "cultra:read cultra:write"
}

Returns a client_id and client_secret.

Manual registration

Register from your profile page under My OAuth Apps. You’ll get a client ID and can configure redirect URIs and scopes.

Authorization flow

Barrd requires PKCE for all authorization code grants.

1. Generate PKCE challenge

code_verifier = random_string(43-128 chars)
code_challenge = base64url(sha256(code_verifier))

2. Redirect to authorize

GET /oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=http://localhost:8080/callback
  &response_type=code
  &code_challenge=BASE64URL_CHALLENGE
  &code_challenge_method=S256
  &state=RANDOM_STATE
  &scope=cultra:read cultra:write

The user sees a consent page listing the requested permissions. If they’ve previously approved the same scopes for this client, consent is remembered and the redirect happens immediately.

3. Exchange code for token

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=http://localhost:8080/callback
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&code_verifier=ORIGINAL_VERIFIER

Returns:

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "...",
  "scope": "cultra:read cultra:write"
}

4. Use the token

GET /api/v2/tasks?project_id=my-project
Authorization: Bearer ACCESS_TOKEN

5. Refresh when expired

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Revoking tokens

POST /oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=ACCESS_OR_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Users can also revoke access to your app from their profile under Connected Apps.

Scopes

Scopes follow the pattern cultra:{resource}:{permission}. Two umbrella scopes cover all resources:

Umbrella scopes

cultra:read Read all resources: sessions, tasks, plans, documents, decisions, projects, graph

cultra:write Read and write all resources

Per-resource scopes for finer control:

Resource scopes

cultra:sessions:read View session data

cultra:sessions:write Create and update sessions

cultra:tasks:read View tasks and progress

cultra:tasks:write Create, update, and delete tasks

cultra:plans:read View plans and status

cultra:plans:write Create and update plans

cultra:documents:read View documents

cultra:documents:write Create and update documents

cultra:decisions:read View decisions

cultra:decisions:write Create and update decisions

cultra:projects:read View projects

cultra:projects:write Create and manage projects

cultra:graph:read View entity relationships

cultra:graph:write Create and manage relationships

A :write scope always includes :read for the same resource. Requesting cultra:tasks:write grants both tasks:read and tasks:write internally.

When a user approves your app, Barrd remembers the granted scopes. Future authorization requests with the same or fewer scopes skip the consent page. If your app requests new scopes, the user sees the consent page again.

Managing your apps

From your profile page under My OAuth Apps:

View client ID, redirect URIs, scopes, and active token count
Update redirect URIs and scopes
Delete the app (revokes all tokens)

Next steps

MCP Tools Reference All 43 tools available via the Barrd MCP server.

API Keys Simpler authentication for direct MCP connections.