Authentication

All Stevora API requests (except health checks) must include a valid API key in the x-api-key header. Keys are scoped to a single workspace and carry the stv_ prefix.

API Key Format

Every Stevora API key starts with the stv_ prefix followed by a random token:

stv_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

The raw key is shown once at creation time. Stevora stores only a SHA-256 hash, so the key cannot be retrieved later.

Authenticating Requests

Pass the key in the x-api-key header on every request:

curl https://api.stevora.dev/v1/workflow-definitions \
  -H "x-api-key: stv_your_api_key_here"

Creating an API Key

To create a new key, call POST /v1/api-keys with an existing key (or an admin token for your first key). See the API Keys page for details.

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

Error Responses

Missing Header

Requests without the x-api-key header receive a 401 response:

{
  "success": false,
  "error": {
    "code": "AUTH_ERROR",
    "message": "Missing x-api-key header"
  }
}

Invalid or Revoked Key

Requests with an unrecognized or revoked key receive a 401 response:

{
  "success": false,
  "error": {
    "code": "AUTH_ERROR",
    "message": "Invalid or revoked API key"
  }
}

Rate Limiting

Requests that exceed the per-workspace rate limit receive a 429 response:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_ERROR",
    "message": "Too many requests"
  }
}

Response Envelope

All API responses follow a consistent envelope:

Success

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

Success (paginated)

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "page": 1,
    "pageSize": 20,
    "total": 42,
    "totalPages": 3
  }
}

Error

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": {}
  }
}

Error Codes

HTTP Status	Code	Description
400	`VALIDATION_ERROR`	Invalid request body or query parameters
401	`AUTH_ERROR`	Missing, invalid, or revoked API key
404	`NOT_FOUND`	Resource does not exist or belongs to another workspace
409	`CONFLICT`	Duplicate resource or concurrent modification
429	`RATE_LIMIT_ERROR`	Too many requests
500	`INTERNAL_ERROR`	Unexpected server error

Public Endpoints

The following paths do not require authentication:

Path	Description
`/health`	Health check
`/ready`	Readiness probe
`/live`	Liveness probe

Authentication

On this page