API Keys
Scoped workspace tokens for SDK, REST, MCP, and automation with mask, events, integrations, and runs scopes.
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 optionallyBLEKLINE_API_URL) in your environment. - Pass
workspaceTokenwhen you constructBleklineClient. - Send the
x-blekline-workspace-tokenheader 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);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.
| Scope | Use | Examples |
|---|---|---|
runs:write | Start governed act runs | POST /api/workspace/cell-runs, createCellRun() |
runs:read | List and inspect runs | GET /api/workspace/cell-runs, listCellRuns() |
integrations:write | Configure connectors and SIEM hooks | Connector OAuth, integration setup APIs |
events:write | Ingest audit and telemetry events | POST /api/events, emitEvent() |
events:read | Read workspace event streams | Compliance exports, audit integrations |
mask:write | Mask prompts at ingress | POST /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.
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).