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](/docs/backend).

## What a session is

When [authentication](/docs/concepts/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.

```http
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](/docs/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."

```python
# 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](/docs/concepts/authorization) decision keys on. Claims in the token (user id, active [organization](/docs/organizations), 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](/docs/users), 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](/docs/integrations) 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](/docs/concepts/authentication) — how sessions are issued
- [Authorization](/docs/concepts/authorization) — what the session's identity is allowed to do
- [Backend requests](/docs/backend) — validating sessions in your server
- [Security](/docs/security) — the defaults behind the token model