Sessions & tokens

When a user signs in to your application, Authdog issues a short-lived session token you can use to authenticate requests to your backend. The token is a signed JSON Web Token (JWT). It says who the user is, and your app checks it on later requests instead of handling their password.

Read how sign-in produces the token in Authentication. To validate it on a server, see Backend requests.

What a session is

The session is the JWT. Authdog signs it when authentication succeeds.

• Signed, not encrypted. Anyone who has the token can read the claims. Only Authdog can produce a valid signature, so a forged token fails validation.
• Scoped to one environment. Each environment signs with its own private key. A token from dev will not validate in production.
• Short-lived. It expires, and Authdog refreshes it. A leaked token is only useful for a short window.

Your app doesn't store the password, and it doesn't re-check the original credential. It verifies this token.

How the session reaches your app

Authdog can hand you the same token two ways. Accept either one on your backend:

• Cookie. After sign-in, Authdog sets authdog-session on the browser. This is the usual path for a first-party web app, because the browser attaches the cookie for you.
• Bearer token. Send Authorization: Bearer <token> when the client can't use a cookie: a mobile app, a single-page app calling your API, or another service.

GET /api/orders HTTP/1.1
Cookie: authdog-session=eyJhbGciOi...
# or
Authorization: Bearer eyJhbGciOi...

Keys: public vs private

Every environment has its own key material. The two kinds do different jobs:

• Signing keys stay inside Authdog and sign sessions. The private half never leaves the platform. Verifiers fetch the public half from the environment's JWKS endpoint.
• The public key (pk_...) is a publishable identifier. It's safe to put in your app. SDKs use it to tell which environment a token belongs to, and where to validate it.

Because the keys are per environment, a token issued in dev can never validate against production. See Deployments when you're promoting configuration across stages.

How your app validates a session

If you're using an Authdog SDK, this is handled for you. The steps underneath are short, and they're worth knowing if you ever validate a token yourself:

1. Read the token from the cookie or the Authorization header.
2. Resolve the environment from the pk_... public key.
3. Confirm the token with the identity provider's userinfo endpoint. That call checks the signature and expiry, honors revocation, and returns a fresh profile.
4. You get a typed context: who the user is, or that nobody is signed in.

# Illustrative: an SDK wraps all of this
ctx = authdog.session(request)   # reads cookie/Bearer, verifies, calls userinfo
if not ctx.is_authenticated:
    return 401
user_id = ctx.user.id

A bad token doesn't throw. A missing or invalid session comes back as "not authenticated," so you can gate on a boolean instead of catching exceptions.

Sessions and authorization

The validated session is the identity every authorization decision starts from. Claims on the token (user id, roles, permissions, and entitlements if you use the Stripe add-on) are enough for a fast check without another lookup. Richer checks (RBAC, ABAC, or FGA) still run on the server against that same identity.

Organizations sit above tenants in the management hierarchy. They aren't an end-user claim inside the environment session.

Lifecycle and revocation

• Expiry and refresh. Sessions are short-lived and refreshed for you, so a leaked token has a bounded window.
• Sign-out. Clears the authdog-session cookie and ends the session.
• Revocation. Suspending or deleting a user, or rotating an environment's keys, invalidates outstanding sessions on the next userinfo check.

Service-to-service tokens

A machine doesn't get a session cookie. An M2M application uses the OAuth 2.0 client credentials grant: it exchanges a client id and secret for a short-lived access token. Validate that token the same way you validate any other bearer token.

Related