Skip to content
Overwatch API

Mint an API key

POST
/v1/keys
curl --request POST \
  --url https://api.overwatch.weareheavy.dev/v1/keys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "sanity-plugin", "expiresInDays": 365 }'

Mint a key bound to the caller’s organization. The organization id is baked into the key, so the holder can’t widen its scope. Optionally restrict the key to a subset of the organization’s sites via siteIds (an agency minting a key per client); an empty or absent list means full organization access.

Session-only, owner/admin. The plaintext key is returned once.

Authorizations

Section titled “ Authorizations ”

Request Bodyrequired

Section titled “ Request Bodyrequired ”
Media typeapplication/json
object
name

A display name for the key.

string
default: CMS plugin
expiresInDays

Days until the key expires. Omit for a non-expiring key.

integer
>= 1
siteIds

Restrict the key to these sites. Every id must belong to the organization. Empty or absent = full organization access.

Array<string>
Example
{
  "name": "sanity-plugin",
  "expiresInDays": 365
}

Responses

Section titled “ Responses ”

201

Section titled “ 201 ”

The new key. Store key now — it is never shown again.

Media typeapplication/json

A freshly minted key. key is the plaintext, shown only in this response.

object
id
required
string
name
required
string | null
key
required

The plaintext API key (wah_…). Store it now — it is never shown again.

string
siteIds
required

The key’s site scope, or null for full organization access.

Array<string> | null
Example
{
  "id": "4f8f6a2e-9d31-4b7a-8c55-1e2d3f4a5b6c",
  "name": "sanity-plugin",
  "key": "wah_CLxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "siteIds": null
}

400

Section titled “ 400 ”

siteIds names a site the organization doesn’t own.

Media typeapplication/json
object
error
required

A human-readable error message.

string
Example
{
  "error": "unknown site ids: 0a1b2c3d-…"
}

401

Section titled “ 401 ”

Missing or invalid credentials.

Media typeapplication/json
object
error
required

A human-readable error message.

string
Example
{
  "error": "invalid api key"
}

403

Section titled “ 403 ”

A dashboard session is required (API-key callers are rejected), or the session’s role does not allow this action.

Media typeapplication/json
object
error
required

A human-readable error message.

string
Example
{
  "error": "a dashboard session is required"
}