Authentication — bRRAIn Docs

API authentication methods: API keys, OAuth 2.0, and session tokens.

Authentication

Every request to the bRRAIn API must be authenticated. bRRAIn supports three authentication methods, each suited to different use cases.

API Keys

API keys are the recommended method for server-to-server integrations, scripts, and CI/CD pipelines. They provide long-lived credentials tied to a specific vault, workspace, and permission scope.

Creating an API Key

  1. Log in to the bRRAIn dashboard at app.brrain.io
  2. Navigate to Settings > API Keys
  3. Click Create New Key
  4. Configure the key:
    • Name: A descriptive label (e.g., "production-ingestion")
    • Scope: read, read-write, or admin
    • Workspace: The workspace this key can access (or "All Workspaces" for vault-wide access)
    • Expiration: Optional expiration date
  5. Copy the key immediately. It is shown only once.

Using an API Key

Include the key in the Authorization header with the Bearer scheme:

curl https://api.brrain.io/v1/memory/retrieve?q=example \
  -H "Authorization: Bearer brr_live_k1a2b3c4d5e6f7g8h9i0"

Key Prefixes

bRRAIn uses prefixed keys for clarity:

| Prefix | Environment | |--------|-------------| | brr_live_ | Production | | brr_test_ | Staging/test | | brr_dev_ | Development |

Key Rotation

To rotate a key without downtime:

  1. Create a new key with the same scope
  2. Update your application to use the new key
  3. Verify the new key works in production
  4. Revoke the old key

The API supports having multiple active keys simultaneously, so there is no need for coordinated cutover.

Revoking a Key

Revoke a key immediately from the dashboard or via the API:

curl -X DELETE https://api.brrain.io/v1/auth/keys/key_abc123 \
  -H "Authorization: Bearer brr_live_ADMIN_KEY"

Revoked keys return 401 Unauthorized on all subsequent requests.

OAuth 2.0

OAuth 2.0 is the recommended method for user-facing applications where end users authenticate with their bRRAIn credentials. It supports the Authorization Code flow with PKCE for enhanced security.

Authorization Code Flow

  1. Redirect the user to the authorization endpoint:
https://auth.brrain.io/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  scope=memory:read memory:write&
  state=random-csrf-token&
  code_challenge=SHA256_CHALLENGE&
  code_challenge_method=S256
  1. Exchange the authorization code for tokens:
curl -X POST https://auth.brrain.io/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "code_verifier=ORIGINAL_VERIFIER"
  1. Receive the token response:
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "ref_a1b2c3d4e5f6",
  "scope": "memory:read memory:write"
}
  1. Use the access token in API requests:
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Token Refresh

Access tokens expire after 1 hour. Use the refresh token to obtain a new access token:

curl -X POST https://auth.brrain.io/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=ref_a1b2c3d4e5f6" \
  -d "client_id=YOUR_CLIENT_ID"

Available Scopes

| Scope | Description | |-------|-------------| | memory:read | Read and search memory objects | | memory:write | Create and update memory objects | | memory:delete | Delete memory objects | | vault:manage | Create and configure vaults | | workspace:manage | Create and configure workspaces | | admin | Full administrative access |

Session Tokens

Session tokens are used internally by the bRRAIn dashboard and web UI. They are HTTP-only cookies set after a user authenticates through the login page. Session tokens are not suitable for API integrations and are documented here only for completeness.

Sessions expire after 24 hours of inactivity or 7 days maximum, whichever comes first.

Security Best Practices

  1. Never expose API keys in client-side code. Use a backend proxy for browser-based applications.
  2. Use the minimum required scope. If your integration only reads data, use a read-only key.
  3. Rotate keys regularly. Set a rotation schedule (e.g., every 90 days) and automate it.
  4. Monitor key usage. The dashboard shows request counts and last-used timestamps for each key.
  5. Use environment variables. Store keys in environment variables or a secrets manager, never in source code.

Next Steps