Sign in with authreads

Point your OIDC client at the discovery document — it lists every endpoint, supported scope, and the signing algorithm, so you rarely hard-code URLs. auth.example.com below is a placeholder: authreads is a single shared API host per environment (tenants are distinguished by client_id, not by subdomain). The real host for your environment — the value that becomes your issuer — is published in Environments & base URLs. The issuerin the document always equals the origin you fetched it from, as OpenID Connect Discovery 1.0 §4.3 requires, so a conformant library needs no override. Resolve every other endpoint from the document rather than constructing URLs by hand, so a future path change doesn't break your integration:

curl https://auth.example.com/.well-known/openid-configuration
# → {
#   "issuer": "https://auth.example.com",
#   "authorization_endpoint": ".../oauth/authorize",
#   "token_endpoint":         ".../oauth/token",
#   "userinfo_endpoint":      ".../oauth/userinfo",
#   "revocation_endpoint":    ".../oauth/revoke",
#   "end_session_endpoint":   ".../oauth/logout",
#   "backchannel_logout_supported": true,
#   "backchannel_logout_session_supported": true,
#   "jwks_uri":               ".../.well-known/jwks.json",
#   "id_token_signing_alg_values_supported": ["EdDSA"],
#   "code_challenge_methods_supported": ["S256"],
#   "token_endpoint_auth_methods_supported": ["none","client_secret_basic",
#                                              "client_secret_post"],
#   "grant_types_supported": ["authorization_code","refresh_token",
#                             "client_credentials",
#                             "urn:ietf:params:oauth:grant-type:token-exchange"],
#   "scopes_supported": ["openid","profile","email","memberships",
#                        "offline_access","account:sessions"]
# }

OIDC clients are registered by hand in the admin dashboard — there is no dynamic/self-service registration endpoint. One active app can hold at most one active OIDC client; revoke and re-register if you need to start over.

1. Open the credential form
   In the admin dashboard, go to API and credentials → Create credential → Sign in with Authreads, then pick the application this client belongs to. Any active app is eligible — unlike a login-password credential, the app does not need This app signs users in enabled.
2. Choose the client type — this is permanent
   Confidential (server application) or Public (browser or native application, PKCE only, no secret). This cannot be changed after creation; register a new client if you got it wrong.
3. Add redirect and logout URIs
   One exact URI per line. Every URI, in both fields, must be:

   • An absolute HTTPS URL, except that native authorization and post-logout callbacks may use plain HTTP on localhost, 127.0.0.1, or [::1].
   • Free of a userinfo/password component and free of a #fragment.
   • Free of wildcards — matching is exact-string, not prefix or pattern. For the three native loopback hosts only, the callback port may differ on both authorization and logout so the OS can assign a free port.
   • At most 2048 bytes, and not duplicated within the same list (20 URIs max per list).

   Redirect URIs and post-logout redirect URIs can be edited later; the client type cannot. Add a public HTTPS backchannel_logout_uri if Authreads must notify your server when a session ends. Private, loopback, link-local, credential-bearing, wildcard, and fragment URLs are rejected; DNS is checked again on every delivery. To change them on an existing client, open API and credentials in the admin console, find the Sign in with Authreads row for your application, and choose Manage OIDC client.
4. Pick scopes
   openid is required and always on. Choose from profile, email, memberships, offline_access, and account:sessions— any scope outside this set is rejected. Scopes can be widened or narrowed later; a client can only ever request what it's been granted here.
5. Save the client secret now — it is shown exactly once
   Confidential clients get a client_id and a client_secret, shown once in a reveal dialog; authreads stores only a digest and cannot show it again. Public clients get only a client_id— no secret is ever issued. Rotating a confidential client's secret invalidates the previous one immediately, with no overlap window.

1. Send the user to /oauth/authorize
   Redirect the browser with your client_id, a registered redirect_uri, response_type=code, the scopes you need, a state, a nonce, and a PKCE code_challenge (S256). All of these are required — unlike most OIDC providers, nonceis not optional here, and any parameter the endpoint doesn't recognize (including prompt and max_age) fails the request instead of being ignored:

   GET /oauth/authorize
     ?client_id=<client_id>
     &redirect_uri=https://app.acme.com/callback
     &response_type=code
     &scope=openid%20profile%20email%20memberships
     &state=<opaque>
     &nonce=<opaque>
     &code_challenge=<base64url-sha256>
     &code_challenge_method=S256

2. User authenticates on the hosted page
   authreads renders the login (and OTP, if required), then redirects back to your redirect_uri with ?code=…&state=…. Verify state matches what you sent.
3. Exchange the code at /oauth/token
   Swap the code for tokens, sending the same PKCE code_verifier. How you authenticate depends on the client type you registered — mixing the two patterns is rejected:

   POST /oauth/token — public client (no secret)

   curl -X POST https://auth.example.com/oauth/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=authorization_code" \
     -d "code=<code>" \
     -d "redirect_uri=https://app.acme.com/callback" \
     -d "client_id=<client_id>" \
     -d "code_verifier=<pkce-verifier>"
   # → { "access_token":"…", "id_token":"…", "refresh_token":"…",
   #     "token_type":"Bearer", "expires_in":900, "scope":"openid profile …" }

   POST /oauth/token — confidential client (HTTP Basic)

   curl -X POST https://auth.example.com/oauth/token \
     -u "<client_id>:<client_secret>" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=authorization_code" \
     -d "code=<code>" \
     -d "redirect_uri=https://app.acme.com/callback" \
     -d "code_verifier=<pkce-verifier>"
   # → { "access_token":"…", "id_token":"…", "refresh_token":"…",
   #     "token_type":"Bearer", "expires_in":900, "scope":"openid profile …" }

   Confidential clients: never send client_id in the form body here — a confidential client authenticates with an Authorization: Basic header only (client_secret_basic; curl's -u flag builds it for you). client_secret_post is also supported for libraries that send the client ID and secret in the form. Sending a secret in the form and a Basic header together is rejected with invalid_client. Public clients do the opposite: no Authorization header, and no client_secret — they authenticate with PKCE alone.
4. Call userinfo (optional)
   GET /oauth/userinfo with the access token returns the standard OIDC claims for the signed-in subject. Prefer reading the id_token directly when you can.

Request the email scope to receive both email and the standard email_verified boolean in the ID token. Without that scope, authreads omits both claims entirely; it never emits a guessed value.

The token response can contain three tokens — using the wrong one is the most common OIDC bug:

“I logged out but the token still works” comes from treating logout as one action when it's actually three independent layers:

• End the hosted session — redirect to GET /oauth/logout (the end_session_endpoint). The next /authorize will prompt for login again.
• Revoke the token — POST /oauth/revoke invalidates a refresh (or access) token immediately, cutting off renewal.
• The access token's TTL — an already-issued access token is self-contained and stays valid until it expires, even after logout. That's why access-token lifetimes are short: you rely on the short TTL plus refresh-token revocation, not on “instant” access-token death.

If you send logout state, Authreads echoes it unchanged onto the already-validated post-logout redirect. Use a random correlation value to verify the response belongs to your logout request. It is not a secret channel: do not put tokens, personal data, or application state inside it.

Implement OpenID Connect Back-Channel Logout 1.0 at the HTTPS URI registered on your client. Authreads sends a form-encoded logout_tokenoutside the browser when an OIDC session is revoked or reaches absolute expiry. Delivery is asynchronous: temporary failures are retried at 1, 5, 30, and 120 minutes, then shown as a persistent failure in the client settings. The user's own logout never waits for your endpoint.

POST https://app.acme.com/your-backchannel-logout-uri
Content-Type: application/x-www-form-urlencoded

logout_token=<signed logout+jwt>

• Verify the EdDSA signature and kid with the discovery JWKS.
• Require your issuer and exact client ID in iss/aud, and validate iat/exp.
• Require the standard back-channel logout events member and reject any token containing nonce.
• Deduplicate on jti, then terminate the session identified by sid. Receiving an already-ended session is success.
• Return 200 or 204; do not redirect.

With the account:sessionsscope a signed-in user can see and revoke their own sessions — useful for a “devices & sessions” screen in your product:

• GET /oauth/account/sessions — list the user's active sessions.
• POST /oauth/account/sessions/{session_id}/revoke — sign out one session.
• POST /oauth/account/sessions/revoke-others — sign out everywhere else.