Auth and OIDC API
The Auth and OIDC endpoints are the main integration surface for applications.
Discovery
Section titled “Discovery”GET /.well-known/openid-configuration returns issuer metadata, authorization endpoint, token endpoint, UserInfo endpoint, introspection endpoint, revocation endpoint, JWKS URI, supported response types, supported grant types, supported scopes, and supported PKCE methods.
GET /.well-known/jwks.json returns public signing keys. Applications should use this endpoint to validate token signatures and should respect kid values for rotation.
Authorization
Section titled “Authorization”GET /authorize starts an authorization request. DarkAuth validates the client, redirect URI, response type, scopes, PKCE challenge, organization hint, and optional ZK public key. If the user must authenticate, it creates pending authorization state and sends the browser through the hosted user UI.
POST /authorize/finalize completes a pending authorization request after the user has authenticated and consented. For ZK requests, the caller must include drk_hash; the server stores the hash and returns redirect details so browser code can attach the fragment JWE.
Token exchange
Section titled “Token exchange”POST /token handles authorization code, refresh token, and client credentials grants depending on client configuration. For code grants, DarkAuth verifies redirect URI and PKCE before issuing tokens.
For ZK code grants, the token response includes zk_drk_hash, not the JWE. The app verifies that hash against the fragment before decrypting.
UserInfo
Section titled “UserInfo”GET /userinfo and POST /userinfo return claims for a bearer access token. DarkAuth validates the JWT signature, issuer, expiration, and access-token use before returning claims.
The response always includes sub. profile allows name, and email allows email and email_verified. DarkAuth organization and authorization claims already present in the access token can also be returned, including org_id, org_slug, roles, and permissions.
Introspection
Section titled “Introspection”POST /introspect lets confidential clients validate tokens. The caller authenticates with client_secret_basic and sends token plus optional token_type_hint.
Active access tokens return metadata only to the client named by the token audience or authorized party. Active refresh tokens return metadata only to the client they were issued for. Inactive, expired, malformed, unsupported, or wrong-client tokens return { "active": false }.
Revocation
Section titled “Revocation”POST /revoke revokes refresh tokens. Confidential clients authenticate with client_secret_basic; public clients send client_id.
Access and ID tokens are stateless and short-lived in v1, so revoking them is accepted as a successful no-op. Refresh tokens are removed from server-side session storage when the caller matches the token’s bound client.
Sessions and logout
Section titled “Sessions and logout”GET /session returns the current first-party user session state. POST /logout clears the user session and can participate in post-logout redirects.
Applications should still clear their own local state on logout.