Identity and authorization

Secure access by design

Authenticate people and confidential applications, issue audience-bound tokens, and enforce explicit scopes and workspaces on every operation.

Discovery

Authorization and protected resources

Issuerhttps://auth.docintel.adar.agomoniai.com

Metadata/.well-known/oauth-authorization-server

REST resourcehttps://docintel.adar.agomoniai.com/api/v1

MCP resourcehttps://mcp.docintel.adar.agomoniai.com/mcp

REST and MCP tokens are audience-bound and are not interchangeable.

Two supported identities

Choose the grant for the actor

Interactive

Authorization Code + PKCE

Use browser login, email MFA, consent, S256 PKCE, short-lived access tokens, rotating refresh tokens, and revocation for a human user.

Service

Client Credentials

Use a confidential application, one-time client secret, approved scopes, explicit team workspace grants, and short-lived access tokens for backend automation.

Boundary

Audience-specific tokens

Request the REST or MCP resource explicitly. Each service rejects tokens minted for the other audience.

Public clients never receive a secret

Browser and native clients use PKCE. Confidential applications keep secrets server-side and rotate overlapping credentials without downtime.

Scope model

Permissions and resource boundaries

Scope family	Purpose	Examples
Workspace	Discover and administer workspaces	`workspaces:read`, `workspaces:write`
Documents	Read or ingest content	`documents:read`, `documents:write`
Knowledge	Query or generate intelligence	`knowledge:query`, `knowledge:generate`
Operations	Manage asynchronous processing	`batches:read`, `batches:write`
Workflows	Run and review vertical workflows	`workflows:read`, `workflows:write`
Learning	Read courses, participate, or manage curriculum	`learning:read`, `learning:participate`, `learning:manage`

A granted OAuth scope authorizes a capability, not a resource. Workspace membership, role, course persona, ownership, and document visibility are checked separately.

DocIntel authorization flow

From discovery to governed execution

DocIntel supports authorization-server discovery, protected-resource discovery, dynamic client registration, browser login, email MFA, Authorization Code with PKCE, user-level scope approval, short-lived access tokens, rotating refresh tokens, revocation, and backend token introspection. The two identities above run two different sequences, shown below.

Interactive · Authorization Code + PKCE

A person authorizing a client

01AuthorizeClient redirects the user to /authorize with a PKCE challenge, requested scope, and resource (REST or MCP audience).

02Login + MFAUser signs in with email and password; DocIntel emails a one-time code when MFA is enabled.

03Scope reviewDocIntel intersects requested scopes with scopes an administrator already granted; anything missing pauses for admin approval.

04Authorization codeDocIntel redirects back to the client with a short-lived, single-use code.

05Token exchangeClient exchanges the code and PKCE verifier at /token for an access token and a rotating refresh token.

Sequence diagram

Interactive: Authorization Code + PKCE

sequenceDiagram
    participant U as "User"
    participant C as "Client Application"
    participant A as "DocIntel OAuth Server"
    participant R as "DocIntel REST or MCP"

    C->>A: GET /authorize (PKCE challenge, scope, resource)
    A->>U: Show login page
    U->>A: Email and password
    A->>U: Email MFA code
    U->>A: Verify code
    A->>A: Intersect requested and granted scopes
    A-->>C: Redirect with authorization code
    C->>A: POST /token (code + PKCE verifier)
    A-->>C: Access token + refresh token
    C->>R: Call with Bearer access token
    R-->>C: Authorized result

Service · Client Credentials

A confidential application authorizing itself

01Confidential applicationAn organization owner creates the application and grants it explicit team workspaces.

02Token requestApplication calls /token directly with its client ID, client secret, and requested scope — no browser, no redirect.

03ChecksDocIntel verifies the secret, an optional CIDR allowlist, and that requested scopes are within what has been granted.

04Access token onlyDocIntel returns a short-lived access token; this grant never issues a refresh token.

Sequence diagram

Service: Client Credentials

sequenceDiagram
    participant App as "Confidential Application"
    participant A as "DocIntel OAuth Server"
    participant R as "DocIntel REST or MCP"

    App->>A: POST /token (client_id, client_secret, scope, resource)
    A->>A: Verify secret, CIDR allowlist, and scope grant
    A-->>App: Access token (no refresh token)
    App->>R: Call with Bearer access token
    R-->>App: Response scoped to granted workspaces

MCP adds protected-resource discovery and gateway validation on top of the interactive flow above — see the MCP-specific sequence

Token and credential handling

Production requirements

Validate issuer, audience, expiry, scopes, application, and organization stateKeep tokens and secrets out of URLs and logsEncrypt refresh tokens at restUse short-lived access tokensRotate refresh tokens and confidential secretsSupport bounded secret overlap and explicit revocationRestrict service-token issuance by IPv4 or IPv6 CIDR when requiredIntrospect tokens at the service boundaryPropagate trace IDs, never credentials

Review credential and usage governance