API Keys

API keys authenticate requests to the Stevora API. Each key is scoped to a single workspace and prefixed with stv_. The raw key is returned only once at creation time -- Stevora stores a SHA-256 hash internally.

Create an API Key

POST /v1/api-keys

Creates a new API key for your workspace.

Request Body

Field	Type	Required	Description
`name`	`string`	Yes	A human-readable name for the key (1-100 characters)

Example Request

curl -X POST https://api.stevora.dev/v1/api-keys \
  -H "x-api-key: stv_your_existing_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "production-backend"}'

Response `201 Created`

{
  "success": true,
  "data": {
    "id": "key_abc123",
    "workspaceId": "ws_xyz789",
    "name": "production-backend",
    "key": "stv_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "createdAt": "2026-04-02T12:00:00.000Z"
  }
}

The key field contains the full API key with the stv_ prefix. This value is only returned in the creation response. Store it securely -- it cannot be retrieved again.

Error Responses

Status	Code	Cause
400	`VALIDATION_ERROR`	Missing or empty `name` field
401	`AUTH_ERROR`	Missing or invalid API key

List API Keys

GET /v1/api-keys

Returns all API keys in your workspace. The raw key value is never included in list responses -- only metadata is returned.

Example Request

curl https://api.stevora.dev/v1/api-keys \
  -H "x-api-key: stv_your_api_key"

Response `200 OK`

{
  "success": true,
  "data": [
    {
      "id": "key_abc123",
      "workspaceId": "ws_xyz789",
      "name": "production-backend",
      "lastUsedAt": "2026-04-02T14:30:00.000Z",
      "createdAt": "2026-04-02T12:00:00.000Z",
      "revokedAt": null
    },
    {
      "id": "key_def456",
      "workspaceId": "ws_xyz789",
      "name": "staging-backend",
      "lastUsedAt": "2026-04-01T09:15:00.000Z",
      "createdAt": "2026-03-15T10:00:00.000Z",
      "revokedAt": null
    }
  ]
}

Error Responses

Status	Code	Cause
401	`AUTH_ERROR`	Missing or invalid API key

Revoke an API Key

DELETE /v1/api-keys/:id

Revokes an API key. Revoked keys are immediately rejected on all future requests. This action cannot be undone.

Path Parameters

Parameter	Type	Description
`id`	`string`	The API key ID

Example Request

curl -X DELETE https://api.stevora.dev/v1/api-keys/key_abc123 \
  -H "x-api-key: stv_your_api_key"

Response `200 OK`

{
  "success": true,
  "data": {
    "revoked": true
  }
}

Error Responses

Status	Code	Cause
401	`AUTH_ERROR`	Missing or invalid API key
404	`NOT_FOUND`	API key not found or belongs to another workspace

You cannot revoke the key you are currently authenticating with.

Key Rotation

To rotate an API key without downtime:

Create a new key with POST /v1/api-keys
Update your application to use the new key
Verify the new key is working
Revoke the old key with DELETE /v1/api-keys/:id

API Keys

On this page