API docs by Redocly

ID Gateway Auth API (0.1.0)

Download OpenAPI specification:Download

OpenAPI specification for the ID Gateway authentication endpoints.

The API follows an OAuth2-style authorization code flow (OIDC-lite) with endpoints for initiating authorization, exchanging authorization codes for tokens, and fetching user information for an authenticated session.

Per-Tenant Issuer (RFC 8414 Compliance):

Each tenant has a unique issuer URL following the format: {base_url}/tenants/{tenant_id}

Example: https://auth.credo.io/tenants/550e8400-e29b-41d4-a716-446655440000

The iss claim in access tokens and ID tokens uses this per-tenant issuer format. The tenant_id is also included as a custom claim in access tokens for client convenience.

Initiate authorization by email

Starts an authorization session for a user. If the email does not exist the user record is created automatically. Returns an authorization code and the redirect URI that should be used by the caller.

Rate Limiting: This endpoint is rate-limited by email + IP to prevent brute force attacks. When rate limited, the response includes a Retry-After header indicating when to retry. After repeated failures, the account may be temporarily locked.

Error Handling (RFC 6749 §4.1.2.1): Per RFC 6749, if client_id is unknown/invalid or redirect_uri is mismatched, the server MUST NOT redirect and should return an error directly:

  • Unknown client_id → 400 bad_request
  • Inactive client or tenant → 400 invalid_client
  • redirect_uri not in registered URIs → 400 bad_request
  • Invalid email or redirect_uri format → 400 validation_error
Request Body schema: application/json
required
email
required
string <email> <= 255 characters

User email to authorize or create

client_id
required
string [ 3 .. 100 ] characters

OAuth client identifier

scopes
Array of strings [ 1 .. 20 ] items [ items <= 100 characters ]

Scopes requested for the session (defaults to "openid" when omitted)

redirect_uri
required
string <uri> <= 2048 characters

Redirect URI to return users after authorization

state
string <= 500 characters

Opaque value used to maintain state between request and callback

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Exchange code or refresh token for new tokens

Exchanges a valid authorization code (FR-1) or refresh token (FR-2) for new tokens. For authorization code exchange, the redirect_uri and client_id must match the authorize request. For refresh grant, provide a valid refresh token and the client_id.

Rate Limiting: This endpoint is rate-limited by client_id + IP to prevent credential stuffing. When rate limited, the response includes a Retry-After header indicating when to retry.

Error Handling (RFC 6749 §5.2):

  • Invalid/expired/used authorization code → 400 invalid_grant
  • Invalid/expired/used refresh token → 400 invalid_grant
  • redirect_uri mismatch → 400 invalid_grant
  • Unknown or inactive client → 400 invalid_client
  • Missing required fields → 400 validation_error
  • Unsupported grant_type → 400 bad_request
Request Body schema: application/json
required
One of
grant_type
required
string
Value: "authorization_code"

Must be authorization_code

code
required
string

Authorization code received from /auth/authorize

redirect_uri
required
string <uri>

Redirect URI that matches the authorize call

client_id
required
string

OAuth client identifier used during authorization

Responses

Request samples

Content type
application/json
Example
{}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "refresh_token": "ref_7c9e6679-7425-40de-944b-e07fc1f90ae7",
  • "token_type": "Bearer",
  • "expires_in": 3600,
  • "scope": "openid profile"
}

Revoke access or refresh token (logout)

Implements RFC 7009 token revocation (FR-3). Accepts either access token (JWT) or refresh token (opaque). Idempotent.

Request Body schema: application/json
required
token
required
string

Token to revoke (access or refresh)

client_id
string

OAuth client identifier (optional per RFC 7009, required for public clients)

token_type_hint
string
Enum: "access_token" "refresh_token"

Optional hint for token type

Responses

Request samples

Content type
application/json
{
  • "token": "ref_7c9e6679-7425-40de-944b-e07fc1f90ae7",
  • "token_type_hint": "refresh_token"
}

Response samples

Content type
application/json
{
  • "revoked": true,
  • "message": "string"
}

List active sessions for current user

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "sessions": [
    ]
}

Revoke a specific session by ID

Authorizations:
bearerAuth
path Parameters
session_id
required
string

Target session identifier

Responses

Response samples

Content type
application/json
{
  • "revoked": true,
  • "session_id": "string",
  • "message": "string"
}

Revoke all sessions for current user

Authorizations:
bearerAuth
query Parameters
except_current
boolean
Default: true

Keep the current session active when true

Responses

Response samples

Content type
application/json
{
  • "revoked_count": 0,
  • "message": "string"
}

Delete a user and revoke sessions (admin)

Authorizations:
adminToken
path Parameters
user_id
required
string

Target user identifier

Responses

Response samples

Content type
application/json
{
  • "error": "bad_request",
  • "error_description": "Invalid JSON in request body"
}

Get user information for the authenticated session

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "sub": "7d3e1c6e-7e1c-4b3c-9d7d-31a322b2fbfb",
  • "email": "user@example.com",
  • "email_verified": true,
  • "given_name": "Jane",
  • "family_name": "Doe",
  • "name": "Jane Doe"
}