Sessions

A sign-in creates a session and gives the client a token for it. The client sends the token with later requests, and Behemoth resolves it back to the session. This page covers the session settings, how the token travels, and what a sign-in route answers with.

Configuration #

Two settings shape sessions. BootConfig.Session says how long a session lasts. BootConfig.Router.Carrier says how its token travels over HTTP, and sets the cookie's attributes. Every field of both is optional.

go
ac, err := engine.Boot(ctx, app, db, engine.BootConfig{
    Session: core.SessionConfig{ExpiresIn: 24 * time.Hour},
    Router: httpapi.RouterConfig{
        Carrier: httpapi.TokenCarrierConfig{Delivery: httpapi.DeliveryHeader},
    },
    // ...
})

BootConfig.Session, a core.SessionConfig:

FieldDefaultMeaning
ExpiresIn7 daysHow long a session lasts.
PendingExpiresIn10 minutesHow long a session lasts while it waits for a second factor.
UpdateAge0, offRolling expiration: a session in use is extended by ExpiresIn once less than UpdateAge is left of it. At zero a session ends ExpiresIn after its sign-in, however much it is used. Keep it well below ExpiresIn: a value that is not smaller extends the session, with a database write, on every request. See Rolling expiration.
FreshAge15 minutesHow long after a sign-in a session counts as fresh. See Fresh sessions.
MaxConcurrent0, no limitSessions a user can use at once: active sessions that have not expired. A session that waits for a second factor doesn't count.
EvictOldestOnLimitfalseAt the limit, end the user's oldest active session to make room. A sign-in that waits for a second factor makes room once the second factor passes. When false, a sign-in at the limit is refused with 401 and the code session_limit_reached, before its second factor when it needs one.
CaptureIPAndAgentfalseRecord the client's IP address and user agent on the session.

BootConfig.Router.Carrier, a httpapi.TokenCarrierConfig:

FieldDefaultMeaning
Deliveryhttpapi.DeliveryCookieWhere the token travels. See Token delivery.
CookieNamesession_tokenThe cookie's name, for the deliveries that use one.
CookieDomainemptyThe cookie's Domain attribute, a host name such as example.com. Empty sends the cookie only to the host that set it. See Cookie attributes.
CookieSameSitehttpapi.SameSiteLaxThe cookie's SameSite attribute: httpapi.SameSiteLax, httpapi.SameSiteStrict, or httpapi.SameSiteNone.
CookieInsecurefalseLeaves Secure off the cookie, for development over plain HTTP.

A negative duration, a Delivery that is not one of the four values, and a cookie setting that can't work are configuration errors from Boot. See Cookie attributes for the cookie settings Boot refuses.

Token delivery #

The delivery names where the token travels in both directions: how a sign-in hands it to the client, and where the client's requests carry it.

DeliveryThe sign-in response has the token inA request carries it in
httpapi.DeliveryCookiea Set-Cookie headerthe cookie
httpapi.DeliveryHeaderthe Set-Auth-Token headerAuthorization: Bearer <token>
httpapi.DeliveryBodythe JSON body, under tokenAuthorization: Bearer <token>
httpapi.DeliveryBoththe cookie and Set-Auth-Tokeneither

Cookie. The browser stores the token and sends it by itself. By default the cookie is HttpOnly, Secure, SameSite=Lax, with the path / and no Domain, and expires with the session. See Cookie attributes to change the domain, SameSite, or Secure. When rolling expiration extends the session, the cookie is set again with the new date. Scripts on the page can't read it, and can't delete it either: the sign-out response removes it. See Sign out. This is the choice for a browser application served from the same site as the API. Behemoth checks where each state-changing request comes from under this delivery. See Cross-site requests.

Header. The client reads the token from Set-Auth-Token, keeps it, and sends it as a bearer token. This suits mobile apps, command-line tools, and other servers.

bash
curl \
  -i \
  -X POST localhost:8080/api/auth/sign-in/email \
  -H 'Content-Type: application/json' \
  -d '{"email":"ada@example.com","password":"correct horse"}'
# HTTP/1.1 200 OK
# Set-Auth-Token: r8_x6fau...
# {"user":{"id":"8b41...","email":"ada@example.com", ...}}

curl \
  -X POST localhost:8080/api/auth/sign-out \
  -H 'Authorization: Bearer r8_x6fau...'

A browser script on another origin can read a response header only when your CORS configuration exposes it. With the header delivery and a browser client, add Set-Auth-Token to Access-Control-Expose-Headers. Without it the sign-in succeeds and the script sees no token.

Body. The token is a field of the sign-in response's JSON. The client sends it back the same way as with the header delivery, as a bearer token. Only the way the sign-in hands it over differs. Choose it when reading a response header is awkward for your client, for example a cross-origin browser script.

json
{
  "user": {
    "id": "8b41...",
    "email": "ada@example.com"
  },
  "token": "r8_x6fau..."
}

Both. A sign-in sets the cookie and the header, and a request may carry either. It is for an application with browser and non-browser clients, or one moving from one to the other.

There is no combination with the body. A token is never read from a request's body.

HttpOnly and the path / are fixed. Three fields of RouterConfig.Carrier set the rest:

Your setupSet
The front end and Behemoth share one hostnothing
A server-rendered front end on a sibling subdomain, such as app.example.com next to auth.example.com, has to receive the cookieCookieDomain: "example.com"
The front end is on another site, such as app.example.orgCookieSameSite: httpapi.SameSiteNone, with RouterConfig.BaseURL set and the front end in RouterConfig.TrustedOrigins
Development over plain HTTP on a host other than localhostCookieInsecure: true
go
ac, err := engine.Boot(ctx, app, db, engine.BootConfig{
    Router: httpapi.RouterConfig{
        BaseURL: "https://auth.example.com",
        Carrier: httpapi.TokenCarrierConfig{
            CookieDomain:   "example.com",
            CookieSameSite: httpapi.SameSiteStrict,
        },
    },
    // ...
})

Boot returns a configuration error for these settings:

  • A CookieSameSite that is not one of the three values.
  • A CookieDomain that is not a host name. A leading dot is accepted and ignored.
  • httpapi.SameSiteNone with CookieInsecure. Browsers accept SameSite=None on a Secure cookie only.
  • httpapi.SameSiteNone under a cookie delivery without RouterConfig.BaseURL. The browser then sends the cookie with cross-site requests, and the origin check is what refuses a forged one.
  • A CookieDomain that is neither the host of RouterConfig.BaseURL nor a parent of it. A browser drops such a cookie.

With httpapi.SameSiteStrict, a user who follows a link from another site to your application arrives without the cookie, and appears signed out until the next navigation.

Changing CookieDomain on a running deployment does not replace the cookies browsers already hold. A browser keeps the old cookie next to the new one until it expires, and users may have to sign in again.

The sign-in response #

Every route that signs a user in answers with the same JSON, whichever plugin it belongs to:

CaseBody
signed in{"user": {...}}
a second factor is pending{"status": "requires_second_factor"}
either, with httpapi.DeliveryBodythe same, plus "token": "..."

The response follows these rules:

  • A plugin can add fields of its own next to these. The magic link plugin adds redirect_url.
  • A pending session's token is delivered like any other. The client presents it together with the second factor, which the two-factor plugin checks.
  • When the second factor passes, the answer carries a new token, delivered the same way, and the pending token stops working. Send the second factor once the client's other requests with the pending token have returned: under the cookie deliveries, a late answer to such a request would remove the new cookie.
  • The response has Cache-Control: no-store.
  • Sign-up answers {"user": {...}} too. It creates no session, so it has no token.

The user #

A user is keyed by its column names, the same names a request uses:

json
{
  "id": "8b41bcc4-81f3-46a4-920a-9326d9cb01a1",
  "email": "ada@example.com",
  "firstname": "Ada",
  "lastname": "",
  "email_verified": false,
  "image_url": "",
  "created_at": "2026-10-09T09:21:25.186568934Z",
  "updated_at": "2026-10-09T09:21:25.186568934Z"
}

These are the public columns of users. A column a plugin added to the table appears next to them, under its own name, if the plugin declared it public, and not at all otherwise. See What a client sees of a user.

Rolling expiration #

By default a session ends ExpiresIn after its sign-in, however much it is used. Set UpdateAge to keep an active user signed in: a session that is used when less than UpdateAge is left of it is extended by ExpiresIn from that moment.

go
Session: core.SessionConfig{
    ExpiresIn: 7 * 24 * time.Hour,
    // used in its last day, a session gets seven more
    UpdateAge: 24 * time.Hour,
},

A session is "used" by any request to one of Behemoth's routes that carries its token: the router authenticates every request before the route runs, and that is where the extension happens. A request that carries no token extends nothing.

Only the request that crosses the threshold writes to the database. The others cost nothing extra: with a session cache (BootConfig.KV), a request whose session is not due is checked without a database query.

What the client sees depends on the delivery:

DeliveryThe response of the request that extended the sessionWhat the client does
httpapi.DeliveryCookiesets the cookie again, with the same token and the new expirynothing
httpapi.DeliveryHeader, httpapi.DeliveryBodyhas nothing to addnothing. The client keeps the token without a date, and the server decides when it ends.
httpapi.DeliveryBothsets the cookie again if the request carried the token in the cookienothing

For a route of yours, here /me, and a session that is due:

bash
curl \
  -i localhost:8080/api/auth/me \
  --cookie 'session_token=r8_x6fau...'
# HTTP/1.1 200 OK
# Cache-Control: no-store
# Set-Cookie: session_token=r8_x6fau...; Path=/;
#   Expires=Fri, 16 Oct 2026 18:16:16 GMT; HttpOnly; Secure; SameSite=Lax

The extension behaves as follows:

  • The response that sets the cookie is marked Cache-Control: no-store, also when your handler set another value. It carries the session token, and a cache that stored it could hand the token to someone else. This affects one response per extension, not every response of the route.
  • The token does not change. Only the cookie's date does.
  • FreshAge is not affected. An extended session is no fresher than before. See Fresh sessions.

Sign out #

POST /sign-out of the emailpassword plugin revokes the session the request carries. What happens to the token on the client depends on the delivery:

DeliveryThe sign-out responseWhat the client does
httpapi.DeliveryCookiereplaces the cookie with an empty one that has expired, so the browser drops itnothing
httpapi.DeliveryHeader, httpapi.DeliveryBodyhas nothing to removediscards the token it kept
httpapi.DeliveryBothremoves the cookie, if the request carried its token in the cookiediscards the token if it kept one from the header
bash
curl \
  -i \
  -X POST localhost:8080/api/auth/sign-out \
  --cookie 'session_token=r8_x6fau...'
# HTTP/1.1 200 OK
# Set-Cookie: session_token=; Path=/; Expires=Thu, 01 Jan 1970 00:00:00 GMT;
#   Max-Age=0; HttpOnly; Secure; SameSite=Lax
# {"status":"signed_out"}

The cookie is removed when the sign-out went through. If a hook handler refuses the sign-out, the session is still live and the cookie stays.

A session can also end without a sign-out from that browser: it was revoked from another device, ended with all the user's sessions, or expired. The browser still holds the cookie. The next request it sends to a route behind httpapi.RequireSession is refused with 401, and that response removes the cookie. See Protect your own routes.

Cross-site requests #

A browser attaches the session cookie to every request to your API, including one that a page of another site caused. Under httpapi.DeliveryCookie and httpapi.DeliveryBoth, Behemoth therefore refuses a POST, PUT, PATCH, or DELETE to one of its routes that a browser sent from an origin it does not trust. The check also covers sign-in and sign-up, which need no cookie. Under httpapi.DeliveryHeader and httpapi.DeliveryBody there is no check.

Configure the check with two fields of BootConfig.Router:

go
ac, err := engine.Boot(ctx, app, db, engine.BootConfig{
    Router: httpapi.RouterConfig{
        BaseURL:        "https://auth.example.com",
        TrustedOrigins: []string{"https://app.example.com"},
    },
    // ...
})
FieldDefaultMeaning
BaseURLemptyThe origin a browser reaches Behemoth at: a scheme, a host, and an optional port, without the base path. Requests from it pass.
TrustedOriginsemptyOther origins whose pages may call Behemoth, such as a front end on another host. Each entry is matched exactly. The same list decides where a redirect URL may point.

A value that is not an http or https origin is a configuration error from Boot.

A request passes in these cases:

  • Its method is GET, HEAD, or OPTIONS.
  • Its Origin header is BaseURL or one of TrustedOrigins.
  • It has no Origin header, and its Sec-Fetch-Site header is absent, same-origin, or none. A client that is not a browser, such as a mobile app, a command-line tool, or another server, sends neither header and needs no change.

Every other request is refused with 403 and the code untrusted_origin, before any rate limit or handler runs. That includes a request with Origin: null, which a browser sends from a sandboxed frame or a local file.

bash
curl -i -X POST https://auth.example.com/api/auth/sign-in/email \
  -H 'Origin: https://other.example' -d '{"email":"ada@example.com","password":"correct horse"}'
# HTTP/1.1 403 Forbidden
# {"code":"untrusted_origin","error":"request from an untrusted origin"}

Form content types #

Under the same two deliveries, Behemoth also refuses a state-changing request whose Content-Type is text/plain, application/x-www-form-urlencoded, or multipart/form-data. These are the types an HTML form can send to another origin. The answer is 415 with the code unsupported_content_type. A request with another Content-Type, or with none, passes.

Send JSON bodies as application/json. curl -d sends application/x-www-form-urlencoded unless you name the type:

bash
curl -i -X POST https://auth.example.com/api/auth/sign-in/email \
  -H 'Content-Type: application/json' -d '{"email":"ada@example.com","password":"correct horse"}'

The base URL #

Set BaseURL in production. When it is empty and Boot mounts routes, Boot logs a warning, and Behemoth compares the host and port of Origin with the request's Host header. The scheme is not compared. Behind a reverse proxy that replaces Host with an internal name, that comparison fails and every request from a browser is refused.

The check does not replace CORS. Your server's CORS configuration still decides whether a script on another origin may read a response.

Refusals are counted in the behemoth.http.origin_refused metric by reason. See Telemetry.

Protect your own routes #

go
{Method: http.MethodGet, Path: "/me", Handler: me,
    Middlewares: []httpapi.Middleware{httpapi.RequireSession()}},

The router authenticates every request before its route runs: it reads the token where the delivery says, and puts the caller on the request's context. httpapi.RequireSession answers 401 unless the caller signed in with a valid active session. Your handler reads the session from the caller with identity.CallerFrom(rctx.Ctx).Session(), and the user is Session().UserID. Callers and permissions describes the caller in full. With UpdateAge set, a session that is due has been extended by then, and the session your handler reads has the new expiry. See Rolling expiration.

A request it refuses does not reach your handler. The response is JSON with a message and a code your client can act on:

The requestStatusBodyThe session cookie
has no session token401{"error": "missing session token", "code": "session_missing"}there is none
has a token that belongs to no session401{"error": "invalid session", "code": "session_invalid"}removed
has the token of a revoked session401{"error": "session has been revoked", "code": "session_revoked"}removed
has the token of an expired session401{"error": "session expired", "code": "session_expired"}removed
has the token of a session that waits for a second factor401{"error": "additional verification required", "code": "session_pending"}kept: the client needs it to present the second factor

A revoked or expired session is told apart only while its row exists. After a purge removes the row, its token gets session_invalid. See Remove old rows.

A session that is invalid, revoked, or expired does not come back, so with a cookie delivery the response also removes the cookie. The router does this for any request that carries such a token, whatever its route. A browser can't delete it itself, and would send the dead token with every request until the cookie expired. With httpapi.DeliveryBoth this applies when the token came in the cookie. A request that sent a bearer token keeps its cookie. Clients of the header and body deliveries hold the token themselves and discard it when they get one of these codes.

A 401 always means the client has no usable session. If Behemoth could not check the session, because the database is down for example, the answer is 500 with a generic message, and the error is logged. No cookie is removed, and a client should not sign its user out on a 500.

RequireSession returns these as typed errors and the router writes the response, so your RouterConfig.ErrorMapper shapes them like any other error.

Fresh sessions #

A session is fresh for FreshAge after its sign-in, or after its second factor. httpapi.RequireFreshSession is RequireSession plus that check, for a route that changes something sensitive: the account's email, a password, a deletion. A session that is valid and too old gets 401 with the code session_not_fresh, and the client asks the user to sign in again.

go
Middlewares: []httpapi.Middleware{httpapi.RequireFreshSession(ac.SessionManager)},

Nothing refreshes a session in place. Signing in again is how a user gets a fresh one.

To tell another service who a request is from, exchange the session for a short-lived JWT. See Session tokens.

What a session proved #

A session records the factor its sign-in checked, in Session.Factors, and a session that passes a second factor records its name after the first. A flow reads them on the caller's session, identity.CallerFrom(ctx).Session().

FactorWhat the sign-in checked
passworda password, whether the user was named by email, username, or phone number
emailcontrol of a mailbox: a magic link
smscontrol of a phone number: a code sent by text message
oauththe answer of an OAuth or OpenID Connect provider

The names are constants in core, such as core.FactorPassword. Each names a channel, whichever plugin checked it. A plugin may record a name of its own, in lowercase snake case. A session that code created without naming a factor has none.

Write a sign-in route #

A sign-in flow passes core's checkpoint, auth.signIn.credentialsVerified, once the credential checks out and before it creates the session. A handler there can refuse the sign-in, or ask for a second factor, and the session is then pending. Name the factor your flow checked, in the payload and in SessionMeta:

go
checkpoint, err := ac.Dispatcher.RunBefore(hctx, hooks.HookSignInCredentialsVerified,
    behemoth.M{hooks.HookValueUserID: user.ID, hooks.HookValueFactor: core.FactorEmail})
if err != nil {
    // a handler refused the sign-in
    return nil, err
}
state := models.SessionActive
if stepUp, _ := checkpoint[hooks.HookValueRequireStepUp].(bool); stepUp {
    state = models.SessionPending
}
session, rawToken, err := ac.SessionManager.Create(
    hctx.Ctx,
    user.ID,
    core.SessionMeta{
        State: state,
        Factor: core.FactorEmail,
    },
)
if err != nil {
    return nil, err
}
return &core.SignInResult{User: user, Session: session, RawToken: rawToken, Method: "myplugin"}, nil

hctx is the core.HookContext of your sign-in, and core.FactorEmail stands for what your flow checked (see What a session proved). Behemoth's sign-in plugins also fire auth.signIn.before, .after, and .failed around the flow with core.WithLifecycle, so that rate limits, hook handlers, and the audit log see every sign-in.

The route hands the result to httpapi.WriteSignIn:

go
// the flow above
result, err := p.SignIn(rctx.Ctx, creds)
if err != nil {
    return err
}
// the body above, and the token by the configured delivery
return httpapi.WriteSignIn(rctx, result, nil)

WriteSignIn is what makes the token arrive. If you write the response yourself, call rctx.TokenCarrier.Write(rctx, rawToken, session.ExpiresAt). It sets the cookie or the header. It returns true when the delivery is the body, and then putting the token in your JSON is up to you.

A flow called from code, such as emailpassword.Plugin.SignIn, returns the raw token in its result and delivers nothing. The caller decides what to do with it.

A route that gives the client a value of its own, to be sent back later, can deliver it the way the session token travels. rctx.TokenCarrier.Config() returns the carrier's settings with their defaults applied: Delivery, and the cookie's CookieSameSite and CookieInsecure. The OAuth plugin does this with its binding value. See OAuth.

Write a route that ends the session #

A route that ends its caller's own session takes the token back afterwards with rctx.TokenCarrier.Clear, the counterpart of Write. With a cookie delivery it removes the cookie the request presented its token in, and it does nothing for the other deliveries.

go
func signOutEverywhere(rctx *httpapi.RequestContext) error {
    // behind RequireSession
    session, _ := identity.CallerFrom(rctx.Ctx).Session()
    err := rctx.Auth.SessionManager.RevokeAllForUser(
        rctx.Ctx,
        session.UserID,
        "signed_out_everywhere",
        "",
    )
    if err != nil {
        return err
    }
    // after the revoke succeeded
    rctx.TokenCarrier.Clear(rctx)
    return rctx.Response.JSON(http.StatusOK, behemoth.M{"status": "signed_out"})
}

Call it only after the session has ended. A response that removes the cookie of a session that is still live leaves that session without a client. Do not call it when the session you ended is someone else's, as in an administrator's route: the cookie on the response is the caller's.