API Keys Reference

API keys enable programmatic access to the Groundtruth Platform API. Keys are scoped per tenant and can be restricted to specific engagements or access levels.

Base URL: /api/api-keys

Authentication: All API key management endpoints require cookie-based session authentication only. You cannot use an API key to manage API keys.

Key Format

API keys use the format gt_live_ followed by 32 hexadecimal characters:

gt_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

Keys are stored as SHA-256 hashes in the database. The raw key value is only returned once at creation time. There is no way to retrieve it later.

List API Keys

GET /api/api-keys

Returns all API keys for the authenticated tenant. The raw key value is never included -- only the prefix is shown.

Response

{
  "keys": [
    {
      "id": "clxyz300key",
      "name": "Production CI/CD",
      "prefix": "gt_live_a1b2",
      "scope": "read_write",
      "engagementId": null,
      "lastUsedAt": "2025-06-01T12:30:00.000Z",
      "expiresAt": null,
      "createdAt": "2025-05-15T08:00:00.000Z"
    },
    {
      "id": "clxyz301key",
      "name": "Dashboard Read-Only",
      "prefix": "gt_live_f9e8",
      "scope": "read_only",
      "engagementId": null,
      "lastUsedAt": "2025-06-01T11:00:00.000Z",
      "expiresAt": "2025-12-31T23:59:59.000Z",
      "createdAt": "2025-06-01T09:00:00.000Z"
    }
  ]
}

Example

curl -X GET https://app.groundtruth.ai/api/api-keys \
  -H "Cookie: sb-access-token=..."

Create API Key

POST /api/api-keys

Creates a new API key. The raw key is returned only once in the response. Store it securely.

Request Body

Response

Status: 201 Created

{
  "id": "clxyz302key",
  "name": "Slack Bot Integration",
  "prefix": "gt_live_c4d5",
  "scope": "read_only",
  "key": "gt_live_c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9",
  "createdAt": "2025-06-01T14:00:00.000Z"
}

IMPORTANT: The key field is only returned in this response. Copy and store it in a secure location (e.g., environment variable, secrets manager). It cannot be retrieved again.

Example

curl -X POST https://app.groundtruth.ai/api/api-keys \
  -H "Cookie: sb-access-token=..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack Bot Integration",
    "scope": "read_only"
  }'

Revoke API Key

DELETE /api/api-keys/:id

Revokes an API key by setting a revokedAt timestamp (soft delete). The key immediately stops working for authentication but remains visible in the key list for audit purposes.

Path Parameters

Response

{
  "success": true
}

Example

curl -X DELETE https://app.groundtruth.ai/api/api-keys/clxyz300key \
  -H "Cookie: sb-access-token=..."

Errors

Rotate API Key

PATCH /api/api-keys/:id

Rotates an existing API key. This creates a new key with the same name, scope, and engagement restriction, then revokes the old key. The new raw key is returned in the response.

Path Parameters

Response

{
  "id": "clxyz303key",
  "name": "Production CI/CD",
  "prefix": "gt_live_b2c3",
  "scope": "read_write",
  "key": "gt_live_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
  "createdAt": "2025-06-01T15:00:00.000Z"
}

IMPORTANT: The old key is immediately revoked. Update all integrations with the new key value before discarding the response.

Example

curl -X PATCH https://app.groundtruth.ai/api/api-keys/clxyz300key \
  -H "Cookie: sb-access-token=..."

Errors

Using API Keys

Include the API key in the Authorization header as a Bearer token:

curl -X GET https://app.groundtruth.ai/api/engagements \
  -H "Authorization: Bearer gt_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"

Scope Behavior

Engagement-Scoped Keys

When an engagementId is set on the key, all requests are restricted to that specific engagement. Attempting to access other engagements returns a 403 error.

Rate Limiting

API keys are subject to rate limiting. The current limits are applied per key using a sliding window algorithm. If you exceed the rate limit, the API returns a 429 Too Many Requests response with a Retry-After header.