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
| Method | Route | Description |
|---|---|---|
GET | /.well-known/oauth-authorization-server | Server metadata — issuer, endpoints, code_challenge_methods_supported |
POST | /oauth/register | Dynamic client registration — rate limited to 5/IP/60s |
POST | /oauth/authorize | Authorization request with mandatory PKCE S256 — rate limited to 20/IP/60s |
POST | /oauth/token | Code-for-token exchange and refresh-based renewal — rate limited to 20/IP/60s |
GET | /oauth/authorizations | Lists the authenticated company's connected authorizations |
POST | /oauth/authorizations/:id/revoke | Revokes 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 nameredirect_uris— array of valid URIstoken_endpoint_auth_method—client_secret_basic,client_secret_postornone
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/tokenrequires the same exactredirect_uriused 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 authorizationclientName— the client application's nameclientId— the client's public identifieruserId— the user who authorized the tokenoperations— list of granted operations (e.g.documents:read)createdAt— issue datelastUsedAt— last useexpiresAt— 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
| Token | Lifetime | Configurable |
|---|---|---|
| Authorization code | 10 minutes | Hardcoded |
| Access token | 1 hour | OAUTH_ACCESS_TOKEN_TTL_MS (default 3600000) |
| Refresh token | 30 days | OAUTH_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
Related
- Authentication — user login and authorized clients