Mint an API token

POST

/orgs/{org}/tokens

curl --request POST \
  --url https://api.sloose.com/orgs/org_9f3c/tokens \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "CI — config push", "expiresAt": "example" }'

• Production

Creates a token scoped to this organisation with the admin role, acting as the member who created it — never above that member’s role at the time of each request, so an owner’s token is an admin. The secret is in the response and nowhere else, so store it when you receive it.

Session only. An organisation API token is refused here with 403 SESSION_REQUIRED: a token must not be able to mint or revoke tokens.

Authorizations

• sessionAuth

Parameters

Path Parameters

org

required

The organisation id the session was issued for. A token for one organisation can never read another.

string

Example

org_9f3c

The organisation id the session was issued for. A token for one organisation can never read another.

Request Body^required

Media typeapplication/json

object

name

required

What the token is for. Shown in the token list.

string

>= 1 characters <= 80 characters

Example

CI — config push

expiresAt

An ISO date (midnight UTC) or an ISO timestamp with Z or an offset, kept in UTC. Omitted means the token never expires.

string

Responses

201

Created. secret is not retrievable afterwards.

Media typeapplication/json

object

token

required

object

id

required

string

name

required

string

prefix

required

The token’s leading characters, for recognising it in a list.

string

role

required

string

createdByUserId

required

string

createdAt

required

string

expiresAt

required

string | null

secret

required

Shown once. The server keeps only a hash of it.

string

Example

{
  "secret": "slo_…"
}

400

The request — its body or its query — did not match the schema. issues carries the Zod issue list.

Media typeapplication/json

The error envelope every non-2xx answer uses.

object

error

required

Human-readable explanation.

string

code

Machine-readable reason. Absent on a few legacy 400s.

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

401

You are no longer a member of this organisation.

Media typeapplication/json

object

error

required

string

code

required

string

Allowed values: MEMBERSHIP_GONE

key

additional properties

Example

{
  "code": "MEMBERSHIP_GONE"
}

403

An API token was used, the role is too low, the bearer belongs to another organisation, or the session is a staff member’s view of the organisation: a read-only one as on any write (IMPERSONATION_READ_ONLY), and a write-capable one too (IMPERSONATION_REFUSED), since a token would outlast the view, acting as the member. Like every route behind a session: a session signed in but in no organisation is refused code: NO_ORG, a banned person code: BANNED, and a closed organisation code: ORG_CLOSED.

Media typeapplication/json

object

error

required

string

code

required

string

Allowed values: SESSION_REQUIRED ROLE_REQUIRED ORG_MISMATCH IMPERSONATION_READ_ONLY IMPERSONATION_REFUSED NO_ORG BANNED ORG_CLOSED

key

additional properties

Example

{
  "code": "SESSION_REQUIRED"
}

422

expiresAt is not in the future.

Media typeapplication/json

object

error

required

string

code

required

string

Allowed values: EXPIRY_IN_PAST

key

additional properties

Example

{
  "code": "EXPIRY_IN_PAST"
}

503

The restore switch is on (code: MAINTENANCE): every route but /health and /robots.txt is refused before anything is read, except the operator’s own POST /staff/people/{id}/delete with the ADMIN_TOKEN. Sloose is down for maintenance. Please try again in a few minutes.

Media typeapplication/json

object

error

required

string

code

required

string

Allowed value: MAINTENANCE

Example

{
  "code": "MAINTENANCE"
}

Headers

Retry-After

integer

Seconds until asking again is worth it (300 while the switch is on).