wellknown.id docs
Contents

Reference

OpenID Connect endpoints and tokens

wellknown.id as a standard OpenID Connect provider: discovery, the code flow with PKCE, what the ID token carries, and what isn't served.

Discovery

https://wellknown.id/.well-known/openid-configuration, also served at RFC 8414's name, /.well-known/oauth-authorization-server. It advertises only what's supported: response_types_supported: ["code"], grant_types_supported: ["authorization_code"], code_challenge_methods_supported: ["S256"].

The flow

Use the authorization code flow with PKCE (S256) as a public client, with your domain as the client_id, scope=openid, a nonce, and a redirect_uri from your config. Or, with private_key_jwt, as a confidential client authenticating with a key from your config's jwks (the web SDK). Only the code flow is supported.

Endpoints

Path
/.well-known/openid-configurationdiscovery
/auththe authorization endpoint, by GET only: checks your config, your policy and the PKCE parameters, then the person proves their key
/tokenthe authorization_code grant, with code_verifier (and a client assertion for private_key_jwt)
/jwksthe IdP's public signing keys (RFC 7517)
/.well-known/web-identity, /fedcm.json and /fedcm/*FedCM's files and endpoints, which the web SDK uses
/sdk/web.jsthe web SDK
/.well-known/releases/the signed release log (checking what wellknown.id serves)

Not served: /me (userinfo), logout and sessions, pushed authorization requests, introspection, revocation and dynamic registration. The IdP's routes are an allow-list.

Tokens

  • ID tokens are JWTs signed with the IdP's keys: EdDSA (Ed25519), with ES256 also published for sites that can't verify EdDSA; kid names the key. Claims: iss (https://wellknown.id), sub (the person's did:key at your site), aud (your client_id), exp, iat, nonce, auth_time, amr, at_hash, and where they apply wellknown_succession (a succession statement: getting started), and act and wellknown_grant (someone acting for the person: delegation). They live 10 minutes.
  • Access tokens are opaque, random and live 60 seconds. wellknown.id keeps nothing behind them and has no userinfo endpoint, so they authorize nothing anywhere: everything you learn is in the ID token.
  • Refresh tokens aren't issued.
  • Authorization codes live 60 seconds and are single use.

Errors

A sign-in your policy turns down comes back as the OpenID Connect error access_denied, with error_description naming every rule that matched (denied by policy: not_p256). A config that doesn't validate, or a policy that doesn't compile, is invalid_client, answered without redirecting.