Auth & security

OAuth 2.0, scoped per user, scoped per tenant.

The connector authorizes through a standard OAuth 2.0 authorization-code flow with PKCE. Every token is bound to one user inside one tenant, with explicit scopes the user reviewed on the consent screen. The same row-level security that protects the claimOS web app also protects the connector.

The OAuth dance.

Five steps, all standard OAuth 2.0. Most users never see steps three and four; the assistant handles them.

01
Authorize
The assistant opens app.claimos.net/oauth/authorize with its client id, redirect URI, requested scopes, and a PKCE challenge.
02
Consent
claimOS confirms the user is signed in, then shows a consent screen listing the assistant and the exact scopes being requested.
03
Code
On Allow, claimOS issues a one-time authorization code (5-minute TTL) and redirects back to the assistant.
04
Token
The assistant exchanges the code at /oauth/token, with the PKCE verifier, for a one-hour access token and (if requested) a 30-day refresh token.
05
Use
The assistant calls /api/mcp with Authorization: Bearer <token>. Each call is scoped to the user, the tenant, and the granted scopes.

Endpoints

GET /oauth/authorize — consent screen. Validates client_id, redirect_uri, scope, state, code_challenge.
POST /oauth/token — exchanges code for access + refresh tokens, also handles refresh-token rotation.
POST /oauth/revoke — revokes an access or refresh token immediately.
GET /oauth/.well-known/oauth-authorization-server — RFC 8414 server metadata; assistants discover the authorize and token URLs from here.
POST /api/mcp — the MCP endpoint. Accepts Bearer tokens; legacy scoped API keys are also accepted for backward compatibility.

Scopes.

Three scopes, picked at consent time. Assistants request a subset; users approve or decline that exact set on the consent screen.

claim:read

Read access to every claim record the authenticating user can already see in claimOS: snapshot, timeline, tasks, participants, communications, policy excerpts, evidence, weather report, estimate variance, readiness, and file workspace. Required for every read tool below.

claim:write

Adds permission to create work tasks and append timeline entries. The connector can log a follow-up or record a call summary; it cannot send emails, schedule communications, edit existing records, or delete anything. Issue this scope only when a user wants the assistant to write back to the file.

offline_access

Issues a refresh token so the assistant can keep working when its short-lived access token expires (one hour). Refresh tokens rotate on every use and last 30 days. Without this scope, the user is asked to re-authorize every hour.

Token model.

Access tokens are short-lived (one hour) and bound to a single (user, client, scope) authorization. The assistant sends them as Authorization: Bearer <token> on every MCP call.
Refresh tokens are long-lived (30 days) and only issued when the user grants offline_access. They rotate on every use: a refresh exchange returns a new access token and a new refresh token, and the previous refresh token is invalidated. A refresh token works exactly once.
Storage. Both access and refresh tokens are hashed with a one-way function before persistence. The plaintext is shown to the assistant once at issuance and never again. A database leak does not leak usable tokens.
Revocation. A user-initiated revoke (Connected Apps) marks the underlying authorization revoked, which immediately invalidates every access and refresh token derived from it. The next request returns 401.
Audit trail. Each token issuance, refresh, and revocation is recorded against the (tenant, user, client) tuple with a timestamp. The Connected Apps page shows last-used time per assistant.

Your data, your tenant.

claimOS is multi-tenant. Every record is tagged with a tenant id, and every database query runs through Postgres row-level security policies that enforce that boundary. The connector reuses those same policies. There is no separate query path for the connector that could widen what a user can see; the connector simply runs the same RLS-scoped queries the web app already runs.

Within a tenant, each user's permissions still apply. A paralegal who can only see a subset of claims in the web app sees the same subset through the connector. The connector cannot grant a user access they don't already have.

Data does not leave your tenant in either direction. The MCP tools return JSON to the AI assistant, and the assistant returns text to the user; the AI provider sees only what the user explicitly asked the assistant to fetch on their behalf. Anthropic's and OpenAI's data-handling terms apply to that assistant traffic; claimOS's terms govern the data inside your tenant. Both are linked from our privacy policy.

Revoking access.

Open Admin → Settings → Connected Apps. Each authorized assistant shows the scopes granted, when access was granted, and when it was last used. Revoke is a single click; the next request from that assistant returns 401 within seconds.

Revocation preserves the audit trail. The authorization row is marked revoked rather than deleted, so an investigation later can still see who authorized what, when, and from which assistant.

Open Connected Apps FAQ