API Keys

Scoped workspace tokens for SDK, REST, MCP, and automation with mask, events, integrations, and runs scopes.

Open API keysSDK clientIntegrations manifest

Workspace API keys (blw_…) authenticate programmatic access to the control plane: published runtime policy, governed tool enforce, act runs, and MCP ingress. Each key carries explicit scopes. It is not your browser login session.

Use a workspace token

You can authenticate in three common ways:

  • Set BLEKLINE_WORKSPACE_TOKEN (and optionally BLEKLINE_API_URL) in your environment.
  • Pass workspaceToken when you construct BleklineClient.
  • Send the x-blekline-workspace-token header on REST calls.
import { BleklineClient } from "@blekline/client";

const client = new BleklineClient({
  baseUrl: process.env.BLEKLINE_API_URL ?? "https://app.blekline.com",
  workspaceToken: process.env.BLEKLINE_WORKSPACE_TOKEN!,
  metadata: { clientSurface: "sdk" },
});

const policy = await client.getExecutionPolicy();
console.log(policy.enforcementStage, policy.policy?.compileHash);

const { run } = await client.createCellRun({
  workflowId: "wf_your_workflow_id",
  executionTier: "act",
  toolCall: true,
});
console.log(run.id, run.compileHash);
.env
export BLEKLINE_WORKSPACE_TOKEN=blw_your_workspace_token
export BLEKLINE_API_URL=https://app.blekline.com

Scopes

Grant the minimum scopes for the workload. Orchestration and act runs need runs:write and often runs:read. Tool enforcement at the SDK or MCP boundary uses the same token as runs when policy requires recorded act. Add mask:write only when prompt ingress runs outside IDE hooks.

ScopeUseExamples
runs:writeStart governed act runsPOST /api/workspace/cell-runs, createCellRun()
runs:readList and inspect runsGET /api/workspace/cell-runs, listCellRuns()
integrations:writeConfigure connectors and SIEM hooksConnector OAuth, integration setup APIs
events:writeIngest audit and telemetry eventsPOST /api/events, emitEvent()
events:readRead workspace event streamsCompliance exports, audit integrations
mask:writeMask prompts at ingressPOST /api/mask, IDE hooks, SDK mask()

See Run first workflow for a token with runs:write, and Connect agents and clients for surfaces that consume the same scopes.

Where to create and rotate

Create, name, and revoke keys in the workspace console. Use separate keys for production automation, local development, and CI. Never commit tokens to git or paste them into tickets.

Manage API keys

Workspace token vs session

The web app uses your signed-in session for UI actions. SDKs, MCP, and server-side jobs use workspace tokens with explicit scopes. A session cookie does not replace a scoped blw_ token in automation.

MCP endpoints

MCP connectors and hosted ingress register as workspace endpoints. They authenticate with workspace tokens on enforce and act paths. Register connectors in the app, then wire clients through Connect and the REST reference. Headless smoke from OSS: pnpm verify:integrations after BLEKLINE_WORKSPACE_TOKEN is set (blekline-oss).