FAQ
Quick answers to the most common integration questions.
Does authreads email my users, and can I turn that off?
Authreads sends one notification of its own: an alert when a device is trusted on an account, because a trusted device can then sign in without a one-time code. It states the device, platform, IP address and time, and links to the hosted account-security page where the device can be removed. Other mail — one-time codes, password resets, invitations — is part of a flow you or your user started.
A tenant administrator can disable the trusted-device alert under Authentication → Security policy → Security notifications. It defaults to on, because silence is the wrong default for a security notification. Disabling the email does not disable the evidence — the trusted_device.createdaudit record is still written, and the device still appears in the account's device inventory. If you switch it off, your product is responsible for telling the user instead.
How do I test back-channel logout locally?
Run the receiver on your machine and expose its exact route through a temporary public HTTPS tunnel, then register that URL as backchannel_logout_uri. Authreads rejects localhost, private/link-local addresses, redirects, and plain HTTP in every environment; that production-identical rule prevents the callback from becoming an SSRF path. Return 200 or 204, avoid logging the logout_token, and rotate the tunnel URL out of the client registration when testing ends.
I set an idle timeout — why are my users still signed in?
Authreads enforces the setting on hosted browser sessions and direct/BFF integrations that present x-session-activity. A hosted OIDC relying party owns its application session, so it must track browser activity and end that session after the resolved timeout. Read idle_timeout_minutes from the signed ID-token claim https://authreads.com/claims/session_policy. Register an OIDC back-channel logout URI as well, so Authreads revocation and absolute-expiry decisions can terminate your relying-party session.
Where do I find my Tenant ID?
In API and credentials— it's the atr_…value with a copy button. It's public, so it's safe to keep in plain config.
I lost my app login password — how do I get it back?
You can't retrieve it because only its digest is stored. Open API and credentials, select the login password, and rotate it. The old value keeps working for a 24-hour grace window, so this is safe to do without perfectly synchronizing every caller — but update your secret manager right away and end the grace window early once every caller is confirmed on the new value.
What's the difference between a login password and an API Access secret?
An app login password (alcs_) is for user auth through the application that owns it. The API Access credential is a machine client for the Management API (creating users/orgs). Different systems — see API and credentials.
What goes in headers vs. the request body?
Identity goes in headers — X-Tenant-Id and Authorization: Bearer. The body carries only operation data (email, password, code) — never ids or secrets.
Is the Tenant ID sensitive?
No — the Tenant ID is a public identifier (like an account number). The secret is the sensitive half; keep it in a secret manager and never expose it to a browser or NEXT_PUBLIC_* variable.
Do I have to create every user manually?
No. Create users in the admin dashboard or via the Management API. On a user's first login, your product mirrors their identity automatically from the token — no manual id copying.
Should I build my own login page or use “Sign in with authreads”?
Both hit the same user pool. Build your own form and drive the first-party session flow when you want full control of the UI. Use hosted OIDC (authorization code + PKCE) when you'd rather authreads host the login screen and use a standard OIDC client library.
Can my users manage their own sessions and devices if I host my own login pages?
Yes. Your backend uses an API Access machine token with account-security:readto list the signed-in user's sessions, trusted devices, and display policy. Add account-security:manage only to revoke access. See the self-service account-security walkthrough.
Are there webhooks or pagination on the Management API?
There are no general outbound webhooks today — poll the API, or push your own events in with POST /api/v1/audit. OIDC back-channel logout is the narrow standards-based exception for session termination. Management list endpoints are also currently unpaginated (they return the full set), so don't assume a cursor/limit contract. See Management API.
I changed a platform default — why did my tenants not pick it up?
Tenant policy storage is field-level and sparse. A tenant immediately inherits a changed platform value unless it deliberately customized that field. Saving a value equal to the current platform default removes the override, so later platform changes flow through again. Check the customized / inherited totals on the Security policy screen. If an inherited field does not move, treat it as a migration or API defect rather than copying the new default into every tenant.
Why was my account locked and what does the error mean?
Repeated failed password or one-time-code attempts can temporarily lock sign-in. A direct integration receives 429, code login_temporarily_locked, and Retry-After. Hosted OIDC receives 429, error temporarily_unavailable, extension error_code: login_temporarily_locked, and the same header. Wait the stated seconds before trying again. Ordinary wrong credentials remain generic and do not confirm whether an account exists; policy lockout and the always-on login brake intentionally share one public response.
Why am I getting a 401?
The tenant identity didn't resolve. Re-check the X-Tenant-Id matches your tenant and the Bearer secret belongs to it. Rotating the secret and updating both sides clears most cases.