TILLAUTH · OPERATE

Sessions.

API

Every sign-in creates a session. Give your users a "where you're signed in" screen: list their active sessions, sign out a single device, or sign out everywhere but here. All three calls use the user's own access token — build the UI in your app.

01Read

List sessions

Returns one entry per login session, the current one flagged and pinned first.

GET https://auth.tilldev.dev/v1/sessions
Authorization: Bearer <access_token>

Field	Meaning
`sid`	Session id — pass this to revoke.
`current`	True for the session making this request.
`status`	`active`, `expired`, or `revoked`.
`device_id`	The device this session is bound to (if known).
`ip`	Last-seen IP address.
`country`	Two-letter country the latest token was issued in, when known.
`started_at`	When the session was first created.
`last_seen_at`	When it was last refreshed.

02Write

Sign out a device

Revoke one session by its sid. This ends the whole session — it can never be renewed, and its live token stops being accepted shortly after. A user can only revoke their own sessions.

POST https://auth.tilldev.dev/v1/sessions/revoke
Authorization: Bearer <access_token>
Content-Type: application/json

{ "sid": "<sid>" }

→ { "ok": true, "revoked": 1 }

03Write

Sign out everywhere else

After a password change, or from a "secure my account" button, end every session except the current one in a single call.

POST https://auth.tilldev.dev/v1/sessions/revoke-others
Authorization: Bearer <access_token>

→ { "ok": true, "revoked": 3 }

Note

The session that makes this call stays signed in; every other one is ended.

04Admin

Revoke on someone's behalf

To end a user's sessions from your own back office — offboarding, a support action — call the admin endpoint with the app's provisioning token (the SCIM token from the app's settings) instead of the user's token:

DELETE https://auth.tilldev.dev/admin/apps/<public id>/users/<userId>/sessions
Authorization: Bearer <provisioning token>

→ { "ok": true, "revoked": 2 }

From the dashboard, a user's page has Revoke all; from a terminal, tilldev auth sessions <app> revoke-user <userId>.

For fully automated offboarding driven by your identity provider, see SCIM provisioning — marking a user inactive there revokes their sessions for you.

05Tokens

Refresh tokens

Each refresh token works once. POST /v1/refresh returns a new pair and retires the old token. If a retired token is presented again, TillAuth treats it as stolen and ends the whole session, including the copy the thief holds. Each sign-in and refresh is also scored for risk; see Session risk.

A sign-in on the hosted pages also starts the browser's SSO session, which signs the user in to your other apps without asking again. Ending the session it came from, in any of the ways on this page, ends it too.

Two tabs in one browser often refresh at the same moment. When the same browser presents a token it retired less than 15 seconds ago, it gets a fresh pair instead of being signed out. A replay from any other client, or after 15 seconds, still ends the session.

New refresh tokens start with tau_rt_, so a secret scanner, TillForge's included, can spot one committed by mistake. Tokens issued before keep working. Treat the rest of the value as opaque.

The mfa claim follows the session

An access token carries mfa: true only when the session it came from passed a second factor. Refreshing keeps that value; it never upgrades a session that didn't step up, even when the same user completed MFA elsewhere.