Workspaces

Workspaces provide multi-tenant isolation in Stevora. Every resource -- workflow definitions, runs, API keys, webhooks, and cost data -- belongs to exactly one workspace. API keys are scoped to a workspace, so all requests are automatically filtered to the correct tenant.

Create a Workspace

POST /v1/workspaces

Creates a new workspace. If the Stevora instance has an ADMIN_TOKEN configured, this endpoint requires the token in the x-admin-token header. This prevents unauthorized workspace creation on shared deployments.

Request Headers

Header	Required	Description
`x-admin-token`	Conditional	Required when the server has `ADMIN_TOKEN` set

Request Body

Field	Type	Required	Description
`name`	`string`	Yes	Workspace display name (1-100 characters)
`slug`	`string`	Yes	URL-safe identifier (1-50 characters, lowercase alphanumeric and hyphens only)

Example Request

curl -X POST https://api.stevora.dev/v1/workspaces \
  -H "x-admin-token: your_admin_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "slug": "acme-corp"
  }'

Response `201 Created`

{
  "success": true,
  "data": {
    "id": "ws_xyz789",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "createdAt": "2026-04-02T12:00:00.000Z",
    "updatedAt": "2026-04-02T12:00:00.000Z"
  }
}

After creating a workspace, create an API key for it using POST /v1/api-keys to begin making authenticated requests.

Error Responses

Status	Code	Cause
400	`VALIDATION_ERROR`	Invalid fields: `name` empty, `slug` contains invalid characters, etc.
401	`AUTH_ERROR`	Missing or invalid `x-admin-token` (when `ADMIN_TOKEN` is configured)
409	`CONFLICT`	A workspace with this slug already exists

Slug Format

The slug field must match the pattern ^[a-z0-9-]+$:

Valid	Invalid
`acme-corp`	`Acme Corp` (uppercase, spaces)
`my-team-2`	`my_team` (underscores)
`production`	`my.team` (dots)

Get Current Workspace

GET /v1/workspaces/current

Returns the workspace associated with the API key used in the request. This is useful for verifying which workspace your key belongs to.

Example Request

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

Response `200 OK`

{
  "success": true,
  "data": {
    "id": "ws_xyz789",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "createdAt": "2026-04-02T12:00:00.000Z",
    "updatedAt": "2026-04-02T12:00:00.000Z"
  }
}

Error Responses

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

Workspace Isolation

All API requests are scoped to the workspace of the authenticating API key. This means:

GET /v1/workflow-definitions returns only definitions in your workspace
GET /v1/workflow-runs returns only runs in your workspace
Attempting to access a resource from another workspace returns a 404 NOT_FOUND
There is no way to query across workspaces through the API

This isolation is enforced at the API layer. Every query includes the workspace ID derived from the authenticated API key.

Workspaces

On this page