Sessions and Tokens

Every login (password, OAuth, or device link code) creates a server-side session. The client holds an opaque token; the server holds everything else.

Token Format

Session tokens start with ods_ followed by 256 bits of random data. The plaintext is shown to the client exactly once; the server stores only a SHA-256 hash, so a database leak does not expose usable tokens.

Device Metadata

Each session records the device it was created on: client name and version, device name, model and manufacturer, OS name and version, locale, timezone, user agent, and IP address. The server also tracks when and from which IP the session was last seen, updated at most once every 5 minutes per session.

Users can rename a session’s device label (for example “Living room Apple TV”) from their settings.

Session Lifetime

Sessions do not expire on their own. A session stays valid until it is revoked:

Event	Effect
User signs out	That session is revoked.
User revokes a device from Settings > Security	That session is revoked.
User changes their password	All other sessions are revoked; the current one stays signed in.
Admin action	All of a user’s sessions can be revoked.

Revocation is immediate: the next request with a revoked token fails.

Locked Accounts

Locking an account does not revoke its sessions; it makes them unusable. Requests fail with an account-locked error until the account is unlocked, at which point existing sessions work again. See Rate Limiting and Account Locking.

Sessions vs API Keys

	Session token	API key
Prefix	ods_	odn_
Created by	Logging in	User settings, deliberately
Scope	Full access for the user’s role	Explicit scope allow-list
Admin endpoints	Yes, for admins	Never
Expires	No, valid until revoked	No, valid until revoked
Intended for	Apps and the web UI	Scripts and integrations

Use API keys for automation and keep session tokens inside apps. See API Keys.