# Sessions and tokens

## Tokens

`POST /user_management/token` returns three tokens:

| Token           | Format                | Lifetime      | Notes                                                                                                                                 |
| --------------- | --------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `access_token`  | JWT signed with ES256 | 10 minutes    | `iss` is `https://login.ohauthcat.com`, `aud` your client ID, `sub` the user, with `sid`, `org_id`, `role`, `roles` and `permissions` |
| `id_token`      | JWT                   | 10 minutes    | OIDC claims: `sub`, `email`, `email_verified`, `nonce`, `auth_time`, `amr`                                                            |
| `refresh_token` | Opaque                | Session-bound | Single-use; every refresh returns a new one                                                                                           |

The `amr` claim lists how the user signed in, in the [RFC 8176](https://www.rfc-editor.org/rfc/rfc8176) vocabulary:

| Sign-in method                                 | `amr` values           |
| ---------------------------------------------- | ---------------------- |
| Password                                       | `pwd`                  |
| Magic code, authenticator app or recovery code | `otp`                  |
| Passkey                                        | `hwk`, `user`          |
| Enterprise SSO                                 | `sso`                  |
| Social sign-in                                 | `social`               |
| Two or more of these                           | each value, plus `mfa` |

For example, a password followed by an authenticator app code gives `["pwd", "otp", "mfa"]`. RFC 8176 has no value for a federated sign-in, so SSO and social sign-in use `sso` and `social`. Check for `mfa` to require a second factor, rather than comparing the whole list.

Verify access tokens on your server against the JWKS at `GET https://login.ohauthcat.com/user_management/jwks`. The end-user issuer is different from the SSO token issuer, so one kind of token cannot be used as the other.

## Refresh rotation and reuse

Each refresh token works once. If a used refresh token is presented again, OhAuthCat assumes it was stolen: it revokes the whole session, emits `session.revoked` and answers [`refresh_token_reused`](/errors/refresh_token_reused/).

## Timeouts

| Setting                    | Default |
| -------------------------- | ------- |
| `session_absolute_seconds` | 30 days |
| `session_idle_seconds`     | 7 days  |

## Listing and revocation

- `GET /v1/users/{user}/sessions` lists a user's live sessions.
- `DELETE /v1/users/{user}/sessions/{session}` revokes one.
- `DELETE /v1/users/{user}/sessions` signs the user out everywhere.

From the browser, `POST /user_management/revoke` revokes one token (RFC 7009), and `/user_management/logout` (RP-initiated logout, with `id_token_hint`) ends the whole session. See [hosted login](/user-management/hosted-login/#sign-out-and-revoke).

A revoked session stops at the next refresh, at most 10 minutes later for an access token already issued. Users also see and end their sessions on the hosted account page.
