Sluby
REST APIKeys

Create an API key.

The key belongs to the workspace and is made by the calling member, whose role it acts with (`created_by`); a key with no creator makes keys with no creator. The answer has the shape of a listed key plus `key`, the secret, which is never shown again.

POST
/api/v1/keys

The key belongs to the workspace and is made by the calling member, whose role it acts with (created_by); a key with no creator makes keys with no creator. The answer has the shape of a listed key plus key, the secret, which is never shown again.

Authorization

bearerAuth
headerAuthorizationBearer <token>

A Sluby API key (sluby_...) sent as Authorization: Bearer <key>. Keys carry scopes: upload, read, manage.

Request Body

application/json
  1. body
name*string

Trimmed; no control characters.

Length1 <= length <= 100
scopes?array<>

A scope listed twice counts once.

Items1 <= items
Default
[  "upload",  "read"]
rate_limit?integer

Requests per minute, at most the server’s API_KEY_RATE_LIMIT_MAX (10000 by default).

Range1 <= value <= 100000
Default100

Response Body

Created (the secret is shown once).

application/json
  1. response

A key as listed, plus its secret, which is only ever shown here.

id*string
Formatuuid
name*string
scopes*array<>
rate_limit*integer

Requests per minute.

is_active*boolean
created_at*string
Formatdate-time
expires_at*|

Set while a rotated-out key is in its grace period.

Formatdate-time
prefix*|

The first 12 characters of the key (sluby_ and 6 more), to tell keys apart. Null for keys created before prefixes were stored.

last_used_at*|

When the key last authenticated a request, to the minute: it is written at most once a minute per key. Null if never used since this was recorded.

Formatdate-time
created_by*|

The member who made the key; it acts with their current role and stops while they are removed. Null for a key made from the server (BOOTSTRAP_API_KEY, npm run db:seed-key), made by such a key, or whose maker was deleted: it acts as an admin.

key*string

The raw sluby_... key.

Example Request
curl -X POST 'https://sluby.example.com/api/v1/keys' \  -H 'Content-Type: application/json' \  -d '{  "name": "string"}'
Example Response
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "name": "string",  "scopes": [    "upload"  ],  "rate_limit": 0,  "is_active": true,  "created_at": "2019-08-24T14:15:22Z",  "expires_at": "2019-08-24T14:15:22Z",  "prefix": "string",  "last_used_at": "2019-08-24T14:15:22Z",  "created_by": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string"  },  "key": "string"}

List API keys. GET

Usable keys of the workspace, newest first, with who made each, including rotated-out keys still in their grace period. Pages hold up to 1000 keys; follow next_cursor while has_more is true.

Rotate an API key. POST

Issues a new secret with the same name, scopes and rate limit. The old key stops working now, or after grace_period_seconds (up to 604800) for a zero-downtime switch.