Sluby
REST APIKeys

Rotate an API key.

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.

POST
/api/v1/keys/{id}/rotate

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.

Authorization

bearerAuth
headerAuthorizationBearer <token>

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

Path Parameters

id*string

Key id.

Request Body

application/json
  1. body
grace_period_seconds?integer
Range0 <= value <= 604800
Default0

Response Body

The replacement key, with its secret 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.

rotated_from*string
Formatuuid
previous_key_expires_at*string
Formatdate-time
Example Request
curl -X POST 'https://sluby.example.com/api/v1/keys/string/rotate' \  -H 'Content-Type: application/json' \  -d '{}'
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",  "rotated_from": "c5500ae4-3bf4-4b9d-9292-5dcc0d464d8b",  "previous_key_expires_at": "2019-08-24T14:15:22Z"}

Create an API key. POST

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.

Rename an API key. PATCH

Changes only the name; the secret, scopes and rate limit stay. An unknown key, a revoked key and a key past its grace period answer 404.