Sessions & tokens

A session is the artifact Authdog issues once a user proves who they are, and the thing your application trusts on every request afterward. Understanding how sessions and tokens are minted, delivered, and validated is the key to integrating Authdog correctly and securely.

This page explains the model; for wiring it into a server see Backend requests.

What a session is

When authentication succeeds, Authdog mints a signed JSON Web Token (JWT) describing the authenticated user. That token is the session. It is:

• Signed, not encrypted: anyone can read its claims, but only Authdog can produce a valid signature.
• Scoped to one environment: signed with that environment's private key.
• Short-lived: it expires and is refreshed, so a leaked token is only useful briefly.

Your app never stores passwords or re-checks credentials; it only verifies this token.

How the session reaches your app

Authdog delivers the session two ways, and your backend accepts either:

• Cookie: the authdog-session cookie, set on the browser after sign-in. Ideal for first-party web apps; the browser attaches it automatically.
• Bearer token: an Authorization: Bearer <token> header. Ideal for mobile apps, SPAs calling an API, and service clients.

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 signing keys stay inside Authdog and sign sessions. The private halves never leave the platform; verifiers fetch the public halves from the environment's JWKS endpoint.
• The public key (pk_...) is a publishable identifier, safe to embed in your app. It tells Authdog SDKs which environment a token belongs to and where to validate it.

Because keys are per-environment, a token minted in dev can never validate against production, a strong isolation guarantee. See Deployments for managing keys across stages.

How your app validates a session

An Authdog SDK does this for you, but the model is simple:

1. Read the token from the cookie or Authorization header.
2. Resolve the environment from the pk_... public key.
3. Confirm the token with the identity provider's userinfo endpoint: this verifies the signature and expiry, honors revocation, and returns fresh profile data.
4. Return a typed context: who the user is, or "not authenticated."

# 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

Validation is designed to never throw on a bad token: a missing or invalid session simply yields "not authenticated," so you gate on a boolean rather than catching exceptions.

Sessions and authorization

The validated session is the identity that every authorization decision keys on. Claims in the token (user id, roles/permissions, and, with the Stripe add-on, entitlements) let you make fast decisions without extra lookups, while richer checks (RBAC/ABAC/FGA) run server-side against that identity. Organizations sit above tenants in the management hierarchy; they are not an end-user claim inside the environment session.

Lifecycle and revocation

• Expiry & refresh: sessions are short-lived and refreshed transparently, bounding the blast radius of a leaked token.
• 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

Machines don't get a session cookie. An M2M application uses the OAuth2 client credentials grant to exchange a client id + secret for a short-lived access token, which your services validate exactly like any other bearer token.

Related

• Authentication: how sessions are issued
• Authorization: what the session's identity is allowed to do
• Backend requests: validating sessions in your server
• Security: the defaults behind the token model