API Keys

API Key Management

Personal Access Tokens (PATs) allow you to authenticate API requests without using your password. Each user has at most one active key — creating a new key automatically revokes the previous one.

Check API Key Status

`GET /api/keys/status`

Returns whether the current user has an active API key.

Example

curl -sS \
  -H 'X-API-Key: <YOUR_PAT>' \
  'https://api.sieve.godel-labs.ai/api/keys/status'

Response — key exists (200)

{
  "hasKey": true,
  "keyPrefix": "gds_a1b2",
  "name": "Production API Key",
  "lastUsed": "2026-02-14 10:30:45",
  "createdAt": "2026-01-14 08:15:30"
}

Response — no key (200)

{
  "hasKey": false
}

Create or Reset API Key

`POST /api/keys`

Generates a new Personal Access Token. Any existing key is revoked. The full key value is returned only once.

Request Body (all fields optional)

{
  "name": "Production API Key",
  "expiresIn": 180
}

Field	Type	Description
`name`	string	Descriptive label for the key
`expiresIn`	number	Expiration in days from now (omit for no expiration)

Example

curl -sS -X POST \
  -H 'X-API-Key: <YOUR_PAT>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Production API","expiresIn":180}' \
  'https://api.sieve.godel-labs.ai/api/keys'

Response (201)

{
  "key": "gds_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "keyPrefix": "gds_a1b2",
  "warning": "Copy this key now. It will not be shown again."
}

The full API key is returned only once at creation time. Store it securely — it cannot be retrieved again.

Revoke API Key

`DELETE /api/keys`

Permanently revokes your active API key.

Example

curl -sS -X DELETE \
  -H 'X-API-Key: <YOUR_PAT>' \
  'https://api.sieve.godel-labs.ai/api/keys'

Response (200)

{
  "success": true,
  "message": "API key revoked successfully"
}

Exchange API Key for JWT

`POST /api/keys/exchange`

Exchanges a valid PAT for a short-lived JWT token pair. Authenticated via the X-API-Key header.

Example

curl -sS -X POST \
  -H 'X-API-Key: <YOUR_PAT>' \
  'https://api.sieve.godel-labs.ai/api/keys/exchange'

Response (200)

{
  "accessToken": "eyJhbGci...",
  "refreshToken": "a1b2c3d4-...",
  "expiresIn": 900
}

Field	Description
`accessToken`	Short-lived JWT (15 min). Pass as `Authorization: Bearer <token>`.
`refreshToken`	Use with `POST /api/auth/refresh` to obtain a new access token.
`expiresIn`	Access token lifetime in seconds (900 = 15 minutes).

Security Best Practices

Rotate keys regularly: Create a new key every 90–180 days.
Set expiration dates: Always specify expiresIn to limit exposure from compromised keys.
Don't commit keys: Never store API keys in source control or client-side code.
Revoke immediately: Delete any key you suspect has been compromised.

API Keys

On this page