Onboarding runbook

1. Get onboarded
   You are invited (or sign up) and complete onboarding. This creates your tenant and your owner account in the admin dashboard — nothing for you to configure yet.
2. Configure the login application
   Open Applications, edit the application that owns your login page or service, and enable This app signs users in.
3. Copy the Tenant ID and issue a login password
   Open API and credentials. Copy the public Tenant ID (atr_…), then choose Create credential → Signing users in and issue the reveal-once alcs_… login password. Full detail: Tenant credentials.
4. Configure your server
   Put both values in your app's config — the id as plain env, the secret in a secret manager:

   .env / secret manager

   AUTHREADS_TENANT_ID=atr_xxxxxxxxxxxx     # public — plain env
   AUTHREADS_APP_LOGIN_SECRET=alcs_xxxxxxxx... # secret — store in a secret manager

5. Create users
   Add users from the admin dashboard or the Management API — see Users & teams. There is nothing to copy afterward: a user's identity mirrors into your product automatically on their first login.
6. First login
   A user logs in through your product. The identity platform authenticates them against your tenant and issues a token carrying their granted app access, which your product enforces.

Step 2 above says “the application that owns your login page or service” as if it were one of the products your users open. In a suite — one login host serving several separate product applications — it usually isn't, and nothing above says what to do with the other apps. Four facts settle it:

• One login credential serves the whole login page, regardless of app. The app login secret is resolved by its own id plus your tenant — the caller never sends an app key — so a single credential authenticates the login page no matter which product the user goes on to open. Which apps a signed-in user can reach is decided separately, by the org-type ∩ role ∩ package matrix.
• The app it's attached to contributes exactly one thing: the user pool. It has no other effect on login.
• One active login credential per app.The platform enforces this, so you can't end up with two live login credentials on the same application by accident.
• Login requires both the app and the tenant to be active. This is the one with a sharp edge for a suite: if you attach the login credential to one of your product apps rather than a dedicated login application, disabling that product disables login for every product— the login credential goes inactive along with the app it's hanging off. Register your login host as its own application (with no product surface of its own) to avoid it, especially when the login host lives on a separate domain from any one product.

• Rotate the login password one last time right before production traffic starts, and store the new value only in your secret manager.
• Never commit the secret to source control or put it in a browser-exposed / NEXT_PUBLIC_*-style variable — the Tenant ID is safe to expose, the secret is not.
• Restrict allowed origins for your application to your production domain(s) before removing any development allowances.
• Verify token handling end to end — issuer, audience, and signing-key checks — see Authentication settings.
• Register your production redirect URIs (if you use hosted OIDC) before you deploy — they must match exactly, per environment.
• Honor proxy headers. Behind a load balancer or CDN, configure your edge to overwrite X-Forwarded-Proto/X-Forwarded-Host, then trust those values only from that proxy so URLs use the public https origin instead of an internal loopback address.
• Set session cookies Secure (and an appropriate SameSite) in production — cookies that worked over http://localhost silently fail over HTTPS without it.
• Use separate credentials per environment. Each tenant/environment is isolated with its own issuer, JWKS, and aud; never point production at a staging issuer or reuse production secrets locally.