Create an API key

View .md OpenAPI spec Open in Claude Open in ChatGPT

POST

/v1/organizations/{id}/api-keys

const url = 'https://app.caprid.com/v1/organizations/4/api-keys';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"label":"staging-ci","expires_in":7776000,"namespaces":["acme-staging"]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://app.caprid.com/v1/organizations/4/api-keys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "label": "staging-ci", "expires_in": 7776000, "namespaces": [ "acme-staging" ] }'

The response is the only time the secret is shown. Switchboard keeps only a hash of it.

Authorizations

Parameters

Path Parameters

required

integer

The Organization’s id, from GET /v1/organizations.

Example

Request Body

application/json

object

label

A name to tell the key apart from others. Defaults to api.

string

/^[A-Za-z0-9_-]{1,64}$/

expires_in

Seconds until the key stops working. 0 means never.

integer

namespaces

Limits the key to these Namespaces, each a live Namespace of the Organization. Leave it out for a key that reaches the whole Organization. A limited key manages only the Signing keys, Client tokens and settings of its Namespaces, and can’t create API keys. You can’t change the limit later.

Array<string>

>= 1 items

Example

{
  "label": "staging-ci",
  "expires_in": 7776000,
  "namespaces": [
    "acme-staging"
  ]
}

Responses

201

The new API key, with its secret.

application/json

object

required

Identifies the key for revoking it. Not a secret.

string

label

required

string

preview

required

The first 6 characters of the secret after sb_, so you can tell keys apart.

string

created_at

required

integer

expires_at

Absent for a key that never expires.

integer

last_used_at

Absent for a key that has never been used.

integer

namespaces

The Namespaces the key is limited to, by name. Absent for a key with no limit. A deleted Namespace drops out, so a key whose Namespaces have all been deleted has [] here and can do nothing.

Array<string>

secret

required

The API key itself. Shown only in this response.

string

Example

{
  "id": "3f9a1c07be42",
  "namespaces": [
    "acme-staging"
  ],
  "secret": "sb_R2x0Z9kQ7mVt3xLp8wNc1bYh5sDf2gJr6uEa0zWiTq4"
}

400

The request is malformed or a field is invalid. The message says which.

application/json

object

error

required

string

Example

{
  "error": "the requested grants exceed the key's scope"
}

401

No valid credential. Missing, expired and revoked credentials all get the same response, and so does an API key whose trial has lapsed. An Agent token from before a claim gets a 401 too, once the claim has made the trial a person’s, with a message saying to get a new token.

application/json

object

error

required

string

Example

{
  "error": "the requested grants exceed the key's scope"
}

Headers

WWW-Authenticate

string

Example

Bearer realm="switchboard"

403

Sent with an API key limited to some Namespaces, to a Namespace outside its limit, or to a route that acts on the Organization as a whole. A limited key can never create API keys.

application/json

object

error

required

string

Example

{
  "error": "this API key is limited to the Namespaces acme-staging, and acme isn't one of them"
}

404

No such thing, or not yours. Another customer’s Organization or Namespace is a 404 too, so nobody can tell which ones exist.

application/json

object

error

required

string

Example

{
  "error": "the requested grants exceed the key's scope"
}