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 another workspace from an already authenticated workspace. This endpoint cannot bootstrap the first workspace; accounts receive one at sign-up. If the instance has an ADMIN_TOKEN, that token is also required.

Request Headers

Header	Required	Description
`x-api-key`	Yes	Valid API key for an existing workspace
`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.in/v1/workspaces \
  -H "x-api-key: stv_your_api_key" \
  -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"
  }
}

The create response does not issue an API key for the new workspace. In the hosted product, normal workspace provisioning should happen through account sign-up.

Error Responses

Status	Code	Cause
400	`VALIDATION_ERROR`	Invalid fields: `name` empty, `slug` contains invalid characters, etc.
401	`AUTH_ERROR`	Missing or invalid API key, or invalid `x-admin-token` when 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.in/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