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 a keypair:

• The private key stays inside Authdog and signs sessions. It never leaves the platform.
• The public key (pk_...) is safe to embed in your app. It's how your backend verifies that a token was really signed by your environment.

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. Verify the signature against the environment's public key and check expiry.
3. Confirm the token is still valid by calling the identity provider's userinfo endpoint (this also fetches fresh profile data and honors revocation).
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, active organization, 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.

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