OIDC Endpoints

stubIdP exposes a standard OpenID Connect endpoint set. The base path depends on the runtime:

Runtime	Base URL
Node.js CLI	`http://localhost:8484`
Cloudflare Workers	`https://<worker>.workers.dev`

Discovery

GET {base}/.well-known/openid-configuration

Returns the standard OIDC Provider Metadata document, including all endpoint URLs, supported scopes, response types, and signing algorithms.

Authorization

GET {base}/auth

Initiates the authorization code flow. Standard OIDC query parameters:

Parameter	Required	Description
`client_id`	Yes	Must match the configured client ID
`redirect_uri`	Yes	Must match the configured redirect URI
`response_type`	Yes	`code`
`scope`	Yes	Space-separated scopes (e.g. `openid profile email`)
`state`	Recommended	Opaque value for CSRF protection
`nonce`	Recommended	Value for replay attack prevention

Token

POST {base}/token

Exchanges an authorization code for tokens. Supports the authorization_code grant type.

Request body (form-encoded):

Field	Description
`grant_type`	`authorization_code`
`code`	Authorization code received from the callback
`redirect_uri`	Must match the original authorization request
`client_id`	Client ID
`client_secret`	Client secret

The response includes access_token, id_token, and optionally refresh_token when offline_access is requested.

UserInfo

GET {base}/me

Returns claims about the authenticated user. Requires a valid Bearer access token in the Authorization header.

JWKS

GET {base}/jwks

Returns the JSON Web Key Set used to verify token signatures. Use this endpoint in your application for automatic key discovery.

End session

GET {base}/session/end

Initiates RP-Initiated Logout (OpenID Connect RP-Initiated Logout 1.0).

Parameter	Description
`id_token_hint`	Previously issued ID token. Used to identify the session to end.
`post_logout_redirect_uri`	URI to redirect to after logout. Must match the value configured via `--post-logout-redirect-uri` / `STUBIDP_POST_LOGOUT_REDIRECT_URI`.
`state`	Opaque value passed back to the client in the post-logout redirect.

When --skip-prompt is enabled, stubIdP auto-approves logout without showing a confirmation page and immediately performs back-channel logout notifications before destroying the session.

Dynamic Client Registration

These endpoints are only available when stubIdP is started with --enable-registration.

Register a client (RFC 7591)

POST {base}/register

Registers a new client. When --registration-initial-access-token is set, the request must include Authorization: Bearer <token>.

Request body (JSON):

Field	Required	Description
`redirect_uris`	Yes	Array of allowed redirect URIs
`client_name`	No	Human-readable client name
`grant_types`	No	Defaults to `["authorization_code"]`
`response_types`	No	Defaults to `["code"]`

The response includes client_id, client_secret, registration_client_uri, and registration_access_token.

Read client configuration (RFC 7592)

GET {base}/register/{client_id}

Returns the current registration metadata for the client. Requires Authorization: Bearer <registration_access_token>.

Update client configuration (RFC 7592)

PUT {base}/register/{client_id}

Replaces the client’s registration metadata. The full client object must be supplied (not a partial patch). Requires Authorization: Bearer <registration_access_token>.

Delete a client (RFC 7592)

DELETE {base}/register/{client_id}

Removes the client registration. Requires Authorization: Bearer <registration_access_token>.

Health

These endpoints are not part of the OIDC spec and are served at the root path regardless of runtime.

Liveness

GET /healthz

Always returns 200 OK when the server process is running. Use this for liveness probes.

{ "status": "ok" }

Readiness

GET /readyz

Returns 200 OK when stubIdP is ready to serve traffic, or 503 Service Unavailable if any check fails. Use this for readiness probes.

Checks:

Check	Always present	Description
`oidc`	Yes	OIDC provider initialized and issuer set
`db`	When DB configured	Database reachable via `SELECT 1`

Example response (all healthy):

{
  "status": "ok",
  "checks": {
    "oidc": { "status": "ok" },
    "db": { "status": "ok" }
  }
}

Example response (DB unreachable):

{
  "status": "error",
  "checks": {
    "oidc": { "status": "ok" },
    "db": { "status": "error", "error": "Connection refused" }
  }
}