API Keys: create, list, update, and revoke credentials

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"
    }
  ]
}

ApiKey[]

Array of API key metadata objects.

Show ApiKey fields

string

Unique key ID. Use this to update or revoke the key.

string

Display name for the key.

string

First 16 characters of the key (e.g. ow_live_sk_a3f8). Use this to identify the key in logs without exposing the full secret.

string

The role this key carries: owner, admin, or viewer.

string | null

ISO 8601 expiration timestamp, or null if the key does not expire.

string | null

ISO 8601 timestamp of the most recent authenticated request made with this key, or null if the key has never been used.

string

ISO 8601 creation timestamp.

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

string

required

A descriptive name for the key, e.g. "CI deploy key" or "Grafana dashboard".

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.

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"
  }
}

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

string

required

The API key ID.

Request body

string

New display name for the key.

string

New role: owner, admin, or viewer. You cannot assign a role higher than your own.

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

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"

Overview

Endpoints

API Keys: create, list, update, and revoke credentials

List API keys

Response

Example

Create an API key

Request body

Response

Example

Update an API key

Path parameters

Request body

Response

Example

Revoke an API key

Path parameters

Response

Example

​List API keys

​Response

​Example

​Create an API key

​Request body

​Response

​Example

​Update an API key

​Path parameters

​Request body

​Response

​Example

​Revoke an API key

​Path parameters

​Response

​Example

List API keys

Response

Example

Create an API key

Request body

Response

Example

Update an API key

Path parameters

Request body

Response

Example

Revoke an API key

Path parameters

Response

Example