# Sessions and sign-out

A person can have a session in your application and a separate login session
with Udibo Identity. Decide which one an action ends before adding sign-out or
device controls. This guide starts after
[your first application sign-in](https://www.udibo.com/docs/identity/get-started).

## Choose what sign-out means

| Action                           | Session to end                                                          | What to verify                                                          |
| -------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| Sign out of your application     | Your application session                                                | The app refuses protected requests afterward                            |
| Sign out of the identity service | The tenant login session, through its discovered `end_session_endpoint` | A subsequent authorization request no longer reuses that tenant session |
| Sign out another device          | Another tenant login session belonging to the person                    | That session's owned tokens stop authorizing requests                   |

Clearing your app's cookie does not necessarily end the tenant's SSO session.
Ending a tenant session does not erase every application's local cookie. Test
the complete behavior your sign-out button promises, including what happens on
the next API request and the next login.

The [integration guide](https://www.udibo.com/docs/oauth2/guides/use-udibo) owns
the application's BFF wiring. Use
[production session checks](https://www.udibo.com/docs/identity/production#make-sessions-durable)
when choosing storage, refresh behavior, and multi-instance deployment.

## Let people manage their sessions

Your tenant's hosted `/security` page includes session controls. Use the account
API below when you need those controls inside your own application. These list
**tenant login sessions**, not every session stored by your app's BFF.

Call the API on **your tenant's host**, with the signed-in person's access
token. No management scope or dashboard seat is required. The credential selects
the person and tenant; request parameters cannot select another account. Machine
credentials are refused, and this surface is absent on Udibo's operator host.

## List active sessions

`GET /api/account/sessions` returns `{sessions: [...]}`. Each entry includes:

- An opaque `id`
- `createdAt` and `lastActiveAt`
- `ipAddress` and `userAgent`
- A `current` marker

The list excludes revoked, expired, and idle sessions. It never includes secrets
or tokens. `current` identifies the login that issued the presented credential,
not whichever browser cookie happens to accompany the request.

A credential can outlive the login that issued it. In that case no row is
current; the revoke-others operation below requires the person to establish a
live current session first.

## Revoke other sessions

| Request                                    | Result                                                               |
| ------------------------------------------ | -------------------------------------------------------------------- |
| `DELETE /api/account/sessions/{sessionId}` | `204` after revoking one other login session                         |
| `POST /api/account/sessions/revoke-others` | `{revoked: number}` after revoking the person's other login sessions |

Mutations accept no body or an empty object. Revoke-others keeps the live
issuing session and also revokes idle sessions, even though the list omits them.

Revocation stops session-owned tokens on the next request. A third-party grant
that originated from the login retains its existing lifetime; do not promise
that revoking one login also revokes every connected application's grant.

## Handle refusals

| Response                                    | Meaning                                                 | Application behavior                                   |
| ------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------ |
| `409`, `reason: "current_session"`          | The requested session is the credential's current login | Use the sign-out flow instead                          |
| `409`, `reason: "current_session_required"` | Revoke-others has no live current login to preserve     | Ask the person to sign in again before retrying        |
| `404`                                       | The session is unknown or belongs to someone else       | Refresh the list; do not infer another account's state |
| `429`                                       | The shared session-mutation budget is exhausted         | Wait for the number of seconds in `Retry-After`        |

Mutations share a budget of 30 attempts per minute per person with the hosted
security page.

## Verify device controls

Use two signed-in browser contexts. Revoke one from the other, then confirm that
the revoked session's owned tokens are refused and the retained session still
works. Also test an expired current session and the protected current session's
`409` response.

If the app looks signed in while its API refuses requests, use
[the troubleshooting checks](https://www.udibo.com/docs/identity/troubleshooting#the-app-looks-signed-in-but-the-api-refuses).

_Last verified 2026-09-26._