OAuth2 Rail
OAuth2 Rail
Section titled “OAuth2 Rail”OAuth 2.0 and OpenID Connect implementation.
Overview
Section titled “Overview”The OAuth2 Rail provides endpoints for OAuth 2.0 authorization flows and OpenID Connect identity services.
Base URL
Section titled “Base URL”/api/v1/oauth2Authorization Flows
Section titled “Authorization Flows”Authorization Code Flow
Section titled “Authorization Code Flow”- Authorize
GET /api/v1/oauth2/authorizeQuery Parameters:
| Parameter | Description |
|---|---|
client_id | Application client ID |
redirect_uri | Callback URL |
response_type | code |
scope | Requested scopes |
state | CSRF token |
code_challenge | PKCE challenge |
code_challenge_method | S256 |
- Token Exchange
POST /api/v1/oauth2/tokenRequest Body:
{ "grant_type": "authorization_code", "code": "auth_code_here", "redirect_uri": "https://app.example.com/callback", "client_id": "client_123", "client_secret": "secret_xxx", "code_verifier": "pkce_verifier"}Response:
{ "access_token": "eyJhbGciOiJSUzI1NiIs...", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "dGhpcyBpcyBhIHJlZnJl...", "scope": "openid profile email", "id_token": "eyJhbGciOiJSUzI1NiIs..."}Client Credentials Flow
Section titled “Client Credentials Flow”POST /api/v1/oauth2/tokenRequest Body:
{ "grant_type": "client_credentials", "client_id": "client_123", "client_secret": "secret_xxx", "scope": "contracts:read contracts:write"}Refresh Token
Section titled “Refresh Token”POST /api/v1/oauth2/tokenRequest Body:
{ "grant_type": "refresh_token", "refresh_token": "dGhpcyBpcyBhIHJlZnJl...", "client_id": "client_123"}OpenID Connect
Section titled “OpenID Connect”UserInfo
Section titled “UserInfo”GET /api/v1/oauth2/userinfoGet authenticated user information.
Response:
{ "sub": "user_123", "name": "Ahmad Abdullah", "email": "ahmad@example.com", "email_verified": true, "tenant_id": "tenant_456", "roles": ["admin", "compliance_officer"]}Discovery
Section titled “Discovery”GET /.well-known/openid-configurationOpenID Connect discovery document.
GET /.well-known/jwks.jsonJSON Web Key Set for token verification.
Client Management
Section titled “Client Management”Register Client
Section titled “Register Client”POST /api/v1/oauth2/clientsRegister a new OAuth client.
Request Body:
{ "name": "My Application", "type": "CONFIDENTIAL", "redirectUris": ["https://app.example.com/callback"], "allowedScopes": ["openid", "profile", "contracts:read"], "grantTypes": ["authorization_code", "refresh_token"]}List Clients
Section titled “List Clients”GET /api/v1/oauth2/clientsList registered OAuth clients.
Update Client
Section titled “Update Client”PATCH /api/v1/oauth2/clients/:clientIdUpdate client configuration.
Rotate Secret
Section titled “Rotate Secret”POST /api/v1/oauth2/clients/:clientId/rotate-secretRotate client secret.
Revoke Token
Section titled “Revoke Token”POST /api/v1/oauth2/revokeRevoke an access or refresh token.
Scopes
Section titled “Scopes”| Scope | Description |
|---|---|
openid | OpenID Connect |
profile | User profile |
email | Email address |
contracts:read | Read contracts |
contracts:write | Write contracts |
admin | Administrative access |
Grant Types
Section titled “Grant Types”| Grant Type | Use Case |
|---|---|
authorization_code | Web applications |
client_credentials | Machine-to-machine |
refresh_token | Token refresh |
Events
Section titled “Events”| Event | Description |
|---|---|
oauth2.token.issued | Token issued |
oauth2.token.revoked | Token revoked |
oauth2.client.created | Client registered |
oauth2.consent.granted | User consent granted |