API Keys and Scopes

Overview

Workflow Studio operator access is API-key scoped in v1.

Keys are seeded into the worker and evaluated per route. Use separate keys for public operator traffic and internal remote-world traffic.

Scope model

Scope	Allows
`trigger:write`	`POST /v1/runs`
`runs:read`	Run, step, hook, and event read APIs
`runs:write`	`cancel`, `resume`, `rerun`, and `wake`
`deploy:read`	Deployment reads, including active deployment
`deploy:write`	Deployment creation and activation
`world:proxy`	Internal `/v1/world/*` and `POST /v1/queue/publish`
`admin`	Full access

Public lane vs internal lane

The worker separates operator APIs from internal transport APIs.

Public operator routes use the scope model above.
Internal routes require both world:proxy and x-workflow-lane: world-proxy.

Do not expose internal lane credentials to browsers or third-party integrations.

Example seeded keys

workflow.config.ts

import { defineWorkflowStudioConfig } from 'workflow-studio';

export default defineWorkflowStudioConfig({
  worker: {
    auth: {
      seedApiKeys: [
        {
          keyId: 'wk_live_operator',
          secret: process.env.WORKFLOW_COMPUTE_API_KEY!,
          projectId: 'proj_1',
          environment: 'prod',
          scopes: ['trigger:write', 'runs:read', 'runs:write', 'deploy:read', 'deploy:write'],
        },
        {
          keyId: 'wk_live_world_proxy',
          secret: process.env.WORKFLOW_INTERNAL_WORLD_PROXY_KEY!,
          projectId: 'proj_1',
          environment: 'prod',
          scopes: ['world:proxy'],
        },
      ],
    },
  },
});

Use admin only for tightly controlled operational access.

Common auth failures

Response code	Meaning	Recovery
`unauthorized`	Key missing, invalid, or revoked	Send a valid bearer key and confirm the seeded secret matches the caller.
`missing_scope`	Key is valid but lacks the required scope	Add the listed scope or use a key with broader access.
`https_required`	Request used HTTP where HTTPS is required	Retry over HTTPS or relax the policy only for trusted local development.

The worker returns a structured error body with code, message, optional required, and optional recovery fields so automation can handle scope and auth failures predictably.

Overview

Scope model

Public lane vs internal lane

Example seeded keys

Common auth failures

On this page