OAuth API Reference

Base URL

https://your-oauth-server.com

Authorization Endpoint

GET /oauth/authorize

Initiates the OAuth 2.0 authorization flow with PKCE.

Query Parameters:

Parameter	Type	Required	Description
response_type	string	Yes	Must be code
client_id	string	Yes	Your client ID
redirect_uri	string	Yes	Registered redirect URI
scope	string	No	Space-separated scopes
state	string	Yes	CSRF protection token
code_challenge	string	Yes	PKCE code challenge (S256)
code_challenge_method	string	Yes	Must be S256

Example Request:

GET /oauth/authorize?response_type=code
  &client_id=your_client_id
  &redirect_uri=https://yourapp.com/callback
  &state=random_state_string
  &code_challenge=PKCE_challenge_here
  &code_challenge_method=S256

Response:

Redirects to login page, then back to redirect_uri with:

https://yourapp.com/callback?code=AUTH_CODE&state=random_state_string

Token Endpoint

POST /oauth/token

Exchanges authorization code for access token.

Request Body:

Field	Type	Required	Description
grant_type	string	Yes	authorization_code or refresh_token
code	string	Yes*	Authorization code (*for authorization_code)
refresh_token	string	Yes*	Refresh token (*for refresh_token)
client_id	string	Yes	Your client ID
client_secret	string	Yes	Your client secret
redirect_uri	string	Yes*	Must match authorize request (*for authorization_code)
code_verifier	string	Yes*	PKCE code verifier (*for authorization_code)

Example Request (Authorization Code):

curl -X POST https://your-oauth-server.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "AUTH_CODE",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "redirect_uri": "https://yourapp.com/callback",
    "code_verifier": "PKCE_verifier_here"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "read write"
}

Example Request (Refresh Token):

curl -X POST https://your-oauth-server.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "REFRESH_TOKEN",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }'

Token Introspection

POST /oauth/token/verify

Validates and inspects an access token.

Request Body:

{
  "token": "ACCESS_TOKEN"
}

Response:

{
  "active": true,
  "client_id": "your_client_id",
  "username": "user@example.com",
  "scope": "read write",
  "exp": 1234567890,
  "iat": 1234564290
}

Token Revocation

POST /oauth/token/revoke

Revokes an access or refresh token.

Request Body:

{
  "token": "TOKEN_TO_REVOKE",
  "token_type_hint": "access_token"
}

Response:

{
  "success": true
}

Client Registration

POST /oauth/register

Register a new OAuth client.

Request Body:

{
  "name": "My Application",
  "redirectUris": ["https://yourapp.com/callback"],
  "grantTypes": ["authorization_code", "refresh_token"]
}

Response:

{
  "client_id": "generated_client_id",
  "client_secret": "generated_client_secret",
  "name": "My Application",
  "redirectUris": ["https://yourapp.com/callback"],
  "grantTypes": ["authorization_code", "refresh_token"],
  "createdAt": "2024-01-13T00:00:00Z"
}

Client Management

GET /oauth/clients

List all registered clients.

Response:

{
  "clients": [
    {
      "id": "client_id",
      "name": "My Application",
      "redirectUris": ["https://yourapp.com/callback"],
      "createdAt": "2024-01-13T00:00:00Z"
    }
  ]
}

PUT /oauth/clients/:id

Update client configuration.

Request Body:

{
  "name": "Updated App Name",
  "redirectUris": ["https://newdomain.com/callback"]
}

DELETE /oauth/clients/:id

Delete a client (soft delete).

Response:

{
  "success": true
}

Error Responses

All endpoints return errors in this format:

{
  "error": "invalid_request",
  "error_description": "Missing required parameter: code_verifier"
}

Common Error Codes:

• invalid_request: Missing or invalid parameters
• invalid_client: Invalid client credentials
• invalid_grant: Invalid or expired authorization code
• unauthorized_client: Client not authorized for grant type
• unsupported_grant_type: Grant type not supported
• invalid_scope: Requested scope is invalid

Rate Limiting

All endpoints are rate-limited to:

• 100 requests per minute per IP
• 1000 requests per hour per client

Rate Limit Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1234567890

Security

• All endpoints require HTTPS in production
• PKCE (S256) is required for authorization code flow
• Client secrets are stored as bcrypt hashes
• JWT tokens use HS256 signing
• Authorization codes expire after 5 minutes
• Access tokens expire after 1 hour
• Refresh tokens expire after 30 days