Skip to content

OAuth 2.0 Authorization Server ​

The OAuth 2.0 authorization server lets third-party applications and native apps obtain scoped access tokens on behalf of users, without exposing long-lived credentials.

RFCs implemented: 8414 (metadata), 7591 (dynamic registration), 8252 (loopback), 7636 (PKCE), 8707 (resource indicators/audience).

Browser clients can register with token_endpoint_auth_method: "none": the response carries no client_secret because a browser cannot store secrets. Omitting that field keeps the existing confidential registration.

Endpoints ​

MethodRouteDescription
GET/.well-known/oauth-authorization-serverServer metadata — issuer, endpoints, code_challenge_methods_supported
POST/oauth/registerDynamic client registration — rate limited to 5/IP/60s
POST/oauth/authorizeAuthorization request with mandatory PKCE S256 — rate limited to 20/IP/60s
POST/oauth/tokenCode-for-token exchange and refresh-based renewal — rate limited to 20/IP/60s
GET/oauth/authorizationsLists the authenticated company's connected authorizations
POST/oauth/authorizations/:id/revokeRevokes a connected authorization — invalidates live tokens

The metadata, registration, authorization and token endpoints are public (no JWT). Connected authorization endpoints require a Bearer JWT (user session).

Reserved internal scope ​

The server publishes nimo:application-projects:promote in the OAuth metadata for Nimo's confidential BFF. This scope is reserved for the exact client_id named in NIMO_INTERNAL_OAUTH_CLIENT_ID, whose oauth_clients record must be confidential and carry the hash of NIMO_INTERNAL_OAUTH_CLIENT_SECRET. The secret exists only in server configuration; the browser never receives the nbt_ access token or the client secret.

Promotion remains shareable=false and publicSafe=false. On every request the backend validates the client, the scope, the expiry (15 minutes maximum), the token's company and a live OWNER or ADMIN membership. DCR cannot select or reuse the reserved ID, and Origin/headers grant no trust. For the SPA, the cookie-only BFF uses user login, an opaque hash-only session stored in the backend, a host-only Secure/HttpOnly/SameSite=Lax cookie and CSRF in X-Nimo-CSRF-Token; it neither stores nor hands the OAuth token to the browser. Its routes appear in neither OpenAPI nor the SDKs.

Mandatory PKCE ​

code_challenge_method must be S256. plain is not accepted. The code_verifier is validated against the code_challenge with SHA-256.

Dynamic registration (DCR) ​

POST /oauth/register accepts:

  • client_name — the app's display name
  • redirect_uris — array of valid URIs
  • token_endpoint_auth_method — client_secret_basic, client_secret_post or none

For none, isConfidential=false and clientSecretHash=null are stored; no client secret is generated or returned.

Only https:// and loopback http://127.0.0.1:{port} / http://[::1]:{port} are accepted (RFC 8252).

redirect_uri validation ​

  • Registered clients: exact match against redirectUris
  • Authorization codes: /oauth/token requires the same exact redirect_uri used in /oauth/authorize; omitting or changing it rejects the exchange.
  • Codes are consumed with an atomic conditional update to prevent concurrent or repeated exchanges; PKCE S256 remains mandatory for public and confidential clients alike.

Refresh tokens ​

POST /oauth/token with grant_type=refresh_token renews the access token and (optionally) rotates the refresh token. Refresh tokens are opaque (SHA-256).

Connected authorizations ​

GET /oauth/authorizations returns the list of authorizations (active OAuth tokens) issued for the authenticated user's company. It only includes live rows: revoked and already expired ones are left out. Each entry includes:

  • id — identifier of the token row inside the authorization
  • clientName — the client application's name
  • clientId — the client's public identifier
  • userId — the user who authorized the token
  • operations — list of granted operations (e.g. documents:read)
  • createdAt — issue date
  • lastUsedAt — last use
  • expiresAt — expiry date

POST /oauth/authorizations/:id/revoke revokes the entire authorization of that client for that user in the authenticated company. Because refresh-token rotation creates a new row on every renewal, the revocation is not limited to the given row: it cuts every live row of the same authorization, so an id from before a rotation also disconnects the agent. Access and refresh tokens are invalidated immediately and the revocation takes effect on the agent's next request. The operation is idempotent.

Audience (RFC 8707) ​

Access tokens are opaque nbt_ values (not JWTs), so they carry no aud claim. The server stores the client_id alongside the token and applies the resource policy in its strategy. For Nimo's internal channel, that policy requires the allowlisted confidential ID.

Timing constants ​

TokenLifetimeConfigurable
Authorization code10 minutesHardcoded
Access token1 hourOAUTH_ACCESS_TOKEN_TTL_MS (default 3600000)
Refresh token30 daysOAUTH_REFRESH_TOKEN_TTL_MS (default 2592000000)

Access tokens in the internal scope apply an additional 15-minute cap, even when the global OAuth TTL is configured above that value.

Cryptographic material ​

  • Authorization codes: 32 random bytes → hex, SHA-256 hash for single use
  • Access tokens: 32 random bytes in an opaque nbt_ bearer and SHA-256 hash in the database
  • Refresh tokens: 32 random bytes → hex, SHA-256 hash
  • Client secrets: 32 random bytes → hex, SHA-256 hash