Sessions
A session represents the authenticated identity behind a request — the account the access key belongs to, that account's plan, and whether the session is still valid. Use it to confirm who you're acting as and what that account is entitled to.
The session model
A session comes back in one of two shapes. A valid session carries its account, isReadOnly, and created. An invalidated session carries only id and invalidated — nothing else.
| Property | Type | Description |
|---|---|---|
| id | Uid | Unique identifier for the session. |
| account | Account | The account the session belongs to. Valid sessions only. |
| isReadOnly | boolean | Whether the session may only read. When true, write actions return 403 Forbidden — see Access Control. Valid sessions only. |
| created | Timestamp | When the session was created. Valid sessions only. |
| invalidated | Timestamp | When the session was invalidated. Invalidated sessions only — absent while the session is valid. |
Account
The account a session belongs to, including its current plan.
| Property | Type | Description |
|---|---|---|
| id | integer | Unique identifier for the account. |
| name | string | Display name of the account. |
| features | string[] | Identifiers of the features unlocked for the account. |
| suspended | boolean | Whether the account is suspended. |
| plan | Plan | The account's current plan. Omitted when the account has no plan. |
Plan
A subscription plan.
| Property | Type | Description |
|---|---|---|
| id | integer | Unique identifier for the plan. |
| name | string | Display name of the plan, e.g. Mastermind. |
Actions
Get the current session
Returns the session tied to the access key used for the request — the account it belongs to and that account's plan. Use it to confirm the authenticated identity and its entitlements. Calling this endpoint also refreshes the session's last-seen time.
The response depends on whether the session is still valid. A valid session returns the full model, with plan omitted when the account has none. An invalidated session returns only its id and the invalidated timestamp.
{
"id": "s1T2u3V4w5X6y7Z8a9B0c1",
"account": {
"id": 48210,
"name": "Ada Lovelace",
"features": ["spaces", "api"],
"suspended": false,
"plan": {
"id": 3,
"name": "Mastermind"
}
},
"isReadOnly": false,
"created": "2024-04-08T09:00:00Z"
}{
"id": "s1T2u3V4w5X6y7Z8a9B0c1",
"invalidated": "2024-05-01T12:00:00Z"
}