Skip to main content
API keys let you authenticate programmatically with the Overwatch REST API. You can manage keys from the dashboard or through the API itself. Every key is scoped to your organization and carries a role that governs what it can do.
Only organization owners can create, update, or delete API keys. Requests made with an admin or viewer key return 403 Forbidden on all write operations in this section.

​
List API keys

GET /api/v1/api-keys
Returns all API keys in your organization. The response includes metadata and a keyPrefix for identification, but never the full key value — Overwatch stores only a SHA-256 hash after creation.

​
Response

{
  "data": [
    {
      "id": "key_01j...",
      "name": "CI deploy key",
      "keyPrefix": "ow_live_sk_a3f8",
      "role": "admin",
      "expiresAt": null,
      "lastUsedAt": "2025-04-15T09:45:00.000Z",
      "createdAt": "2025-01-15T00:00:00.000Z"
    }
  ]
}
​
data
ApiKey[]
Array of API key metadata objects.

​
Example

curl https://overwatchapp.dev/api/v1/api-keys \
  -H "Authorization: Bearer $API_KEY"

​
Create an API key

POST /api/v1/api-keys
Creates a new API key. The plaintext key is included in the response once and cannot be retrieved again. Store it immediately in a secrets manager or environment variable.

​
Request body

​
name
string
required
A descriptive name for the key, e.g. "CI deploy key" or "Grafana dashboard".
​
role
string
Role to assign to the key: owner, admin, or viewer. Defaults to your own role. You cannot create a key with a higher role than your own.
​
expiresAt
string
Optional ISO 8601 date/time string after which the key is automatically rejected, e.g. "2026-01-01T00:00:00.000Z". Omit for a non-expiring key.

​
Response

Returns 201 Created. The data object includes all the standard metadata fields plus a key field containing the full plaintext API key. 
{
  "data": {
    "id": "key_01j...",
    "name": "CI deploy key",
    "keyPrefix": "ow_live_sk_a3f8",
    "role": "admin",
    "expiresAt": null,
    "createdAt": "2025-04-15T10:00:00.000Z",
    "key": "ow_live_sk_a3f8c2d1e4b5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1"
  }
}
​
data.key
string
The full plaintext API key. This is the only time Overwatch returns the key value. Copy it now.
Overwatch stores only a SHA-256 hash of the key. If you lose the plaintext, you must revoke the key and create a new one.

​
Example

curl -X POST https://overwatchapp.dev/api/v1/api-keys \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI deploy key",
    "role": "admin",
    "expiresAt": "2026-01-01T00:00:00.000Z"
  }'

​
Update an API key

PATCH /api/v1/api-keys/:id
Updates the name, role, or expiration date of an existing key. You cannot rotate the key value itself — to get a new secret, delete the key and create a replacement.

​
Path parameters

​
id
string
required
The API key ID.

​
Request body

​
name
string
New display name for the key.
​
role
string
New role: owner, admin, or viewer. You cannot assign a role higher than your own.
​
expiresAt
string | null
New expiration date as an ISO 8601 string, or null to remove an existing expiration and make the key non-expiring.

​
Response

Returns the updated key metadata with 200 OK. The plaintext key is not included. 
{
  "data": {
    "id": "key_01j...",
    "name": "CI deploy key (updated)",
    "keyPrefix": "ow_live_sk_a3f8",
    "role": "viewer",
    "expiresAt": null,
    "lastUsedAt": "2025-04-15T09:45:00.000Z",
    "createdAt": "2025-01-15T00:00:00.000Z"
  }
}

​
Example

curl -X PATCH https://overwatchapp.dev/api/v1/api-keys/$KEY_ID \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "role": "viewer" }'

​
Revoke an API key

DELETE /api/v1/api-keys/:id
Permanently revokes an API key. Any requests made with the revoked key after deletion return 401 Unauthorized immediately. This action is irreversible.

​
Path parameters

​
id
string
required
The API key ID.

​
Response

{
  "data": { "id": "key_01j..." }
}

​
Example

curl -X DELETE https://overwatchapp.dev/api/v1/api-keys/$KEY_ID \
  -H "Authorization: Bearer $API_KEY"