Workspace Management

A workspace is an isolated environment containing all your integrations, credentials, data stores, and knowledge base documents. Every resource in HeadlessOps belongs to exactly one workspace.

Creating a Workspace

Via the Web UI

1. Log in at app.headlessops.ai
2. Click New Workspace from the workspace switcher
3. Enter a name, slug, and optional description
4. Click Create — you are automatically assigned the OWNER role

Via the API

The authenticated user becomes the OWNER of the new workspace.

curl -X POST https://app.headlessops.ai/api/workspaces \
  -H "Authorization: Bearer iter_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Production",
    "slug": "acme-prod",
    "description": "Production automations for Acme Corp"
  }'

Response:

{
  "id": "ws_abc123",
  "name": "Acme Production",
  "slug": "acme-prod",
  "description": "Production automations for Acme Corp",
  "createdAt": "2026-01-01T00:00:00Z"
}

Tip: After creating a workspace, create iterator/iterator.config.json in your repo with { "workspaceId": "ws_abc123" } so all MCP tool calls resolve the correct workspace automatically.

Listing Workspaces

curl https://app.headlessops.ai/api/workspaces \
  -H "Authorization: Bearer iter_YOUR_KEY"

Returns an array of all workspaces the authenticated user is a member of, including their id, name, slug, and description.

Workspace Settings

Navigate to Workspace Settings in the web UI to manage:

• General — name, slug, description
• Security — require 2FA for all members
• Labels — manage workspace labels, descriptions, and member grants (see Labels & Permissions)
• Danger Zone — delete workspace (irreversible)

API Key Management

API keys are workspace-scoped bearer tokens. They authenticate API requests and automatically resolve to the workspace that issued them — no need to pass workspaceId in the request.

Required role: ADMIN or OWNER

IAM v1 change: API keys created by non-admin members now inherit the label grants of the issuing user. Keys created by ADMINs and OWNERs retain full workspace access. See Labels & Permissions — API Keys for details.

Create an API Key

curl -X POST https://app.headlessops.ai/api/workspaces/ws_abc123/api-keys \
  -H "Cookie: session=YOUR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ci-deploy", "expiresAt": "2027-01-01T00:00:00Z" }'

Response:

{
  "id": "key_abc123",
  "name": "ci-deploy",
  "key": "iter_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "expiresAt": "2027-01-01T00:00:00Z",
  "createdAt": "2026-01-01T00:00:00Z"
}

The full key is returned only once. Store it securely — it cannot be retrieved again.

List API Keys

curl https://app.headlessops.ai/api/workspaces/ws_abc123/api-keys \
  -H "Cookie: session=YOUR_SESSION"

Secret values are never returned in list responses — only metadata (name, expiry, created date).

Revoke an API Key

curl -X DELETE https://app.headlessops.ai/api/workspaces/ws_abc123/api-keys/key_abc123 \
  -H "Cookie: session=YOUR_SESSION"

API Key vs MCP OAuth

When using MCP OAuth, always pass workspaceId explicitly (or use iterator.config.json for automatic resolution).

Naming Conventions

A meaningful description helps AI agents identify the correct workspace without user intervention.

Multi-Workspace Patterns

For teams managing multiple clients or environments:

acme-prod       → Production CRM automations for Acme Corp
acme-staging    → Staging environment for testing new integrations
client-b-prod   → Production data pipelines for Client B
internal-ops    → Internal HeadlessOps tooling and utilities

Each workspace has:

• Its own credentials vault (no cross-workspace secret sharing)
• Its own data stores and knowledge base
• Independent member roster and roles
• Separate API keys
• Its own label registry and grants