Sessions and cookies
How Legation keeps users signed in.
When a user signs in, Legation creates a session and sets an HTTP-only session cookie.
Cookie names
| Cookie | Name over HTTPS | Name over plain HTTP |
|---|---|---|
| Session token | __Secure-legation.session_token | legation.session_token |
| Cached session data, when enabled | __Secure-legation.session_data | legation.session_data |
Over HTTPS the names carry the __Secure- prefix, so production deployments normally use the prefixed names. Cookie names are set for your environment; do not hard-code them in your app. The cookies are HTTP-only, so browser code cannot read them. Use the client to read the session.
What a session records
- The user it belongs to.
- When it expires.
- The IP address and user agent of the request that created it.
Reading the session
Use useSession() in framework clients, or the client's get-session call.
The client does not read or create a session during server-side rendering, and it never writes cookies there. The client is shared across requests in a server process, so it ignores session data on the server to avoid leaking one user's session into another request. If your server reads the session itself, you can pass that session to the client in the browser; the client uses it only while it has no session of its own, then keeps it up to date.
Legation's session and your application's session
id0n hosts Legation at your environment endpoint. That hosted service is the issuer: it signs users in, holds the Legation session and sets the cookies above for the endpoint's own address. Your application talks to it through the client.
| Legation session | Your application's session | |
|---|---|---|
| Who creates it | Legation, at your environment endpoint | Your application, if it keeps one |
| Where it lives | HTTP-only cookies for the environment endpoint | Wherever your application stores it |
| How your app learns about it | The client's session calls, or useSession() | Your own code |
| How it ends | Sign-out through the client, expiry or revocation | Your own code |
- Treat Legation as the source of truth for who is signed in. If your application keeps its own session or cache, check it against Legation and end it when the user signs out.
- Signing out of Legation does not clear state your application stores itself, and clearing your own state does not sign the user out of Legation. Do both.
- When Legation acts as an OAuth provider, the tokens an OAuth client receives are separate from the Legation session.
- Legation's cookies belong to the environment endpoint, not to your application's address, so your application's server does not receive them with its own requests. Server-side session checks are published with the Legation API reference.
Fresh sessions
Some sensitive actions, such as changing a password or deleting an account, need a recent sign-in. If the session is too old, Legation returns SESSION_NOT_FRESH or SESSION_EXPIRED ("Re-authenticate to perform this action."). Ask the user to sign in again.
See Session management.