Workspaces - Obol

A workspace is Obol’s tenant boundary: workspace_id is on every Postgres row and every Redis key. Keys, policy, connections, approvals, receipts, and usage all hang off one. See Tenancy and identity for the model. Every route on this page requires an operator session. See Authentication.

These routes are scoped to the signed-in operator’s own memberships. GET /workspaces returns only workspaces the caller belongs to, and org_id narrows that set, never widens it.

Workspace object

string

required

Workspace id, prefixed ws_.

string

required

The organization that owns the workspace.

string

required

Human-readable name, unique within the organization.

string

required

One of dev, stage, prod. Environment is enforced downstream: a dev key can never reach a prod connection.

boolean

required

When true, every action outside workspace.read, audit.read, and usage.read answers 409.

integer

required

The workspace’s policy-snapshot version. Incremented when a new snapshot is staged for the gateway.

Create a workspace

POST /api/v1/workspaces Requires membership in the target organization. Returns 201. Creation grants the creator an owner membership in the same transaction, so a workspace never exists without someone accountable for it. It also writes version-1 snapshot-publication intent in that transaction, then publishes the snapshot after the commit.

Body

string

required

The organization to create in, 1–64 characters. The operator must already be a member of a workspace in this organization. A first-time operator gets their organization from GET /api/v1/me, which provisions one.

string

required

1–128 characters. Must be unique within the organization.

string

default:"dev"

One of dev, stage, prod.

curl -X POST "$OBOL_CONTROL_URL/api/v1/workspaces" \
  -H "Authorization: Bearer $OBOL_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"org_id": "org_acme", "slug": "demo-dev", "env": "dev"}'

{
  "id": "ws_01hxyz",
  "org_id": "org_acme",
  "slug": "demo-dev",
  "env": "dev",
  "frozen": false,
  "snapshot_version": 1
}

Errors

Status	Condition
`400`	`env` is not `dev`, `stage`, or `prod`.
`401`	No session, or the session did not verify.
`403`	`{"detail": "not a member of that organization"}`. Without this check, `org_id` would be a caller-supplied string that lets anyone plant a workspace in another tenant’s organization.
`409`	`{"detail": "workspace slug already exists in this org"}`.
`422`	`org_id` or `slug` failed length validation.

A snapshot-publication failure after the commit is not an error the caller can act on and is not surfaced: the workspace exists, its pending publication row is durable, and the reconciliation sweep converges it.

List workspaces

GET /api/v1/workspaces Returns every workspace the signed-in operator is a member of.

Query parameters

string

Narrow the result to one organization. Omitting it returns memberships across all organizations.

curl "$OBOL_CONTROL_URL/api/v1/workspaces?org_id=org_acme" \
  -H "Authorization: Bearer $OBOL_SESSION_TOKEN"

{
  "workspaces": [
    {
      "id": "ws_acme_prod",
      "org_id": "org_acme",
      "slug": "acme-prod",
      "env": "prod",
      "frozen": false,
      "snapshot_version": 1
    }
  ]
}

Response

array

required

Workspace objects. Empty when the operator has no memberships matching the filter.

This route is not paginated.

Get a workspace

GET /api/v1/workspaces/{workspace_id} Requires the workspace.read action, which every role holds.

Path parameters

string

required

Workspace id, prefixed ws_.

curl "$OBOL_CONTROL_URL/api/v1/workspaces/ws_acme_prod" \
  -H "Authorization: Bearer $OBOL_SESSION_TOKEN"

{
  "id": "ws_acme_prod",
  "org_id": "org_acme",
  "slug": "acme-prod",
  "env": "prod",
  "frozen": false,
  "snapshot_version": 1
}

Errors

Status	Condition
`401`	No session, or the session did not verify.
`404`	No such workspace, or the operator is not a member. Both answer identically.

​Workspace object

​Create a workspace

​Body

​Errors

​List workspaces

​Query parameters

​Response

​Get a workspace

​Path parameters

​Errors

Workspace object

Create a workspace

Body

Errors

List workspaces

Query parameters

Response

Get a workspace

Path parameters

Errors