OAuth 2.0 / OIDC API
OpenID Connect and OAuth 2.0 endpoints for third-party authentication. The platform dynamically generates an RSA-2048 keypair on startup for signing tokens.
GET /api/oauth/.well-known/openid-configuration
Returns the OpenID Connect discovery document. This is the first endpoint OIDC clients should call to discover all other endpoints.
Auth: None
Response 200:
{
"issuer": "https://api.example.com/api/oauth",
"authorization_endpoint": "https://api.example.com/api/oauth/authorize",
"token_endpoint": "https://api.example.com/api/oauth/token",
"userinfo_endpoint": "https://api.example.com/api/oauth/userinfo",
"jwks_uri": "https://api.example.com/api/oauth/jwks",
"response_types_supported": ["code", "token", "id_token"],
"subject_types_supported": ["public"],
"id_token_signing_alg_values_supported": ["RS256"],
"scopes_supported": ["openid", "profile", "email", "groups"]
}
GET /api/oauth/jwks
Returns the JSON Web Key Set (JWKS) containing the platform's public RSA key. Used by clients to verify ID and access token signatures.
Auth: None
Response 200:
{
"keys": [
{
"kid": "plat-key-1",
"use": "sig",
"alg": "RS256",
"kty": "RSA",
"n": "base64url-encoded-modulus",
"e": "AQAB",
"key_ops": ["verify"]
}
]
}
Error 500:
{ "error": "OAuth public key is not initialized" }
GET /api/oauth/authorize
The OAuth 2.0 authorization endpoint.
If no token query parameter is provided, the user is redirected to the portal's OAuth consent page at /oauth/authorize with the original parameters forwarded.
If a valid portal JWT token is provided, an authorization code is generated (valid for 5 minutes) and the user is redirected back to the redirect_uri with the code and state.
Auth: None (redirects to portal for authentication if not already authenticated)
Query Parameters:
| Param | Type | Required | Description |
|---|---|---|---|
| client_id | string | yes | Client identifier |
| redirect_uri | string | yes | Callback URL after authorization |
| response_type | string | no | Response type (default: code) |
| scope | string | no | Space-separated scopes (default: openid) |
| state | string | no | CSRF protection state |
| token | string | no | Pre-authenticated portal JWT |
Response 302 (no token): Redirect to {PORTAL_URL}/oauth/authorize?client_id=...
Response 302 (with token): Redirect to {redirect_uri}?code={uuid}&state={state}
Error 401 (invalid token):
{ "error": "Invalid or expired portal token" }
POST /api/oauth/token
Exchanges an authorization code for an access token and ID token. Supports extracting the client_id from an HTTP Basic Auth header as a fallback.
The authorization code is consumed immediately (single-use). Returns:
- Access token: Signed with RS256, valid for 1 hour, contains
id,email,name,role - ID token: Signed with RS256, contains standard OIDC claims including
sub,name,email,groups,roles
Auth: None (uses the authorization code for validation)
Request Body:
{
"code": "uuid-from-authorize",
"client_id": "your-client-id",
"redirect_uri": "https://yourapp.com/callback",
"grant_type": "authorization_code"
}
Response 200:
{
"access_token": "eyJhbGciOiJSUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 3600,
"id_token": "eyJhbGciOiJSUzI1NiIs..."
}
Error 400:
{ "error": "Invalid or expired authorization code" }
GET /api/oauth/userinfo
Returns information about the authenticated user. Requires a Bearer access token obtained from the token endpoint. The token is verified using the platform's RSA public key.
Auth: Bearer token (access token from /api/oauth/token)
Headers:
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Response 200:
{
"sub": "user-uuid",
"name": "John Dev",
"email": "[email protected]",
"email_verified": true,
"groups": ["developer"],
"roles": ["developer"]
}
Error 401:
{ "error": "Authorization header with Bearer token is required" }
OAuth Flow Summary
Client App Cairn API
| |
|--- GET /.well-known --------->| Discover endpoints
|<-- Discovery document --------|
| |
|--- GET /authorize ----------->| User authenticates (or redirects to portal)
|<-- Redirect with code --------|
| |
|--- POST /token -------------->| Exchange code for tokens
|<-- access_token + id_token ---|
| |
|--- GET /userinfo ------------>| Fetch user profile
|<-- User claims ---------------|
Error Codes
| Status | Error | Description |
|---|---|---|
| 400 | client_id and redirect_uri are required |
Missing required authorize params |
| 400 | Invalid or expired authorization code |
Code not found or expired (5 min) |
| 401 | Invalid or expired portal token |
Bad JWT on /authorize |
| 401 | Authorization header with Bearer... |
Missing auth on /userinfo |
| 401 | Invalid access token: ... |
Bad or expired access token |
| 404 | User not found |
User does not exist |
| 500 | OAuth public key is not initialized |
RSA keypair not generated |