OIDC API

YorAuth is a fully compliant OpenID Connect Provider. These endpoints implement the OIDC Core 1.0 specification, including discovery, authorization code flow with PKCE, token exchange, and RP-initiated logout.

OIDC Client Management

OIDC clients (relying parties) are managed via the V1 API. Each client belongs to an application.

Authentication for Client Management

Requires a valid JWT access token with the oidc:manage permission:

Authorization: Bearer {access_token}

Discovery Document

GET /.well-known/openid-configuration

Returns the OIDC provider configuration document. No authentication required.

Response

200 OK

{
  "issuer": "https://api.yorauth.com",
  "authorization_endpoint": "https://api.yorauth.com/oidc/authorize",
  "token_endpoint": "https://api.yorauth.com/oidc/token",
  "userinfo_endpoint": "https://api.yorauth.com/oidc/userinfo",
  "jwks_uri": "https://api.yorauth.com/.well-known/jwks.json",
  "end_session_endpoint": "https://api.yorauth.com/oidc/logout",
  "response_types_supported": ["code"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "scopes_supported": ["openid", "profile", "email", "offline_access"],
  "token_endpoint_auth_methods_supported": ["client_secret_post"],
  "code_challenge_methods_supported": ["S256"]
}

JWKS

GET /.well-known/jwks.json

Returns the JSON Web Key Set containing the public keys used to verify ID tokens. No authentication required.

Response

200 OK

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "alg": "RS256",
      "kid": "2026-02-25",
      "n": "sJ9p...",
      "e": "AQAB"
    }
  ]
}

Authorize

GET /oidc/authorize

Authorization endpoint for the authorization code flow with PKCE. Creates an authorization code after validating the request parameters. Requires a valid YorAuth JWT to identify the user — the user must be authenticated in the application before initiating OIDC authorization.

Authentication

Requires Authorization: Bearer {access_token} (YorAuth user JWT for the application).

Query Parameters

Response

200 OK

{
  "code": "auth_code_abc123...",
  "state": "random_state_xyz",
  "redirect_uri": "https://your-app.com/callback",
  "branding": {
    "name": "Acme Corp",
    "logo_url": "https://example.com/logo.png",
    "color": "#1a73e8",
    "background": "#ffffff"
  }
}

Error Responses

Token Exchange

POST /oidc/token

Exchange an authorization code for access token, refresh token, and ID token. Also handles refresh token grants.

Authorization Code Grant

Refresh Token Grant

Response

200 OK

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "oidcrt_abc123...",
  "id_token": "eyJhbGciOiJSUzI1NiJ9...",
  "scope": "openid profile email"
}

The id_token is a signed JWT (RS256) containing standard OIDC claims:

{
  "iss": "https://api.yorauth.com",
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "aud": "your-client-id",
  "exp": 1708864800,
  "iat": 1708861200,
  "nonce": "abc123",
  "email": "alice@example.com",
  "name": "Alice"
}

Error Responses

UserInfo

GET /oidc/userinfo

Returns claims about the authenticated user. The claims included depend on the scopes in the access token.

Authentication

Requires Authorization: Bearer {access_token} (the access token from the OIDC token exchange).

Response

200 OK

Response includes claims based on granted scopes:

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "email": "alice@example.com",
  "email_verified": true,
  "name": "Alice",
  "picture": "https://example.com/avatar.png"
}

RP-Initiated Logout

GET /oidc/logout

Initiate logout from the OIDC provider. Revokes any OIDC refresh tokens associated with the session, then redirects to the post_logout_redirect_uri if provided and registered.

Query Parameters

If post_logout_redirect_uri is provided and registered, the user is redirected there. Otherwise a "logged out" page is shown.

OIDC Client Management

List Clients

GET /api/v1/applications/{applicationId}/oidc/clients

List all OIDC clients for the application.

Response

200 OK

{
  "data": [
    {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "client_id": "client_abc123",
      "name": "My Web App",
      "description": "Frontend SPA",
      "logo_url": null,
      "redirect_uris": ["https://app.example.com/callback"],
      "allowed_scopes": ["openid", "profile", "email"],
      "is_active": true,
      "created_at": "2026-02-25T12:00:00Z"
    }
  ]
}

Create Client

POST /api/v1/applications/{applicationId}/oidc/clients

Create a new OIDC client. The client secret is returned only on creation.

Request Body

Response

201 Created

{
  "data": {
    "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "client_id": "client_abc123",
    "client_secret": "secret_xyz456...",
    "name": "My Web App",
    "description": "Frontend SPA",
    "redirect_uris": ["https://app.example.com/callback"],
    "allowed_scopes": ["openid", "profile", "email"],
    "is_active": true
  }
}

Get Client

GET /api/v1/applications/{applicationId}/oidc/clients/{clientId}

Retrieve a single OIDC client. The client secret is not included.

Update Client

PUT /api/v1/applications/{applicationId}/oidc/clients/{clientId}

Update an OIDC client's settings. All fields are optional.

Request Body

Delete Client

DELETE /api/v1/applications/{applicationId}/oidc/clients/{clientId}

Delete an OIDC client. Existing active tokens issued to this client are not revoked.

Response

204 No Content