This guide covers the full connection flow: from creating a key to watching your agent produce its first output.
1) Decide on scopes before creating the key
Scope decisions should follow from what the agent actually needs to do. Common patterns:
Read-only research agent — reads sources, writes a summary artifact:
env:read
artifacts:write
Memory-maintaining agent — reads everything, updates facts, writes outputs:
env:read
artifacts:write
files:propose ← memory/ writes become reviewable proposals
Activity-reporting agent — does its own storage, just logs events:
env:read
events.write
Only grant files:propose for folders where you want a review step. If an agent can write artifacts/ directly, those writes land without approval. If it can only propose, every write is a staged diff you review.
2) Create the Agent Access key
In your workspace, go to Agents → Agent Access → New key.
- Name it after the agent or pipeline it belongs to
- Select the scopes from step 1
- Copy the secret — it is shown once
The key is workspace-scoped. It cannot access any other workspace.
3) Sign your requests
Every Agent Access request requires four HMAC-SHA256 headers:
| Header | Value |
|---|---|
x-integration-key-id | Your key id |
x-integration-timestamp | Unix timestamp in seconds |
x-integration-nonce | A unique value per request |
x-integration-signature | HMAC-SHA256 of the canonical string |
Canonical string format:
METHOD
pathWithQuery
timestampSeconds
nonce
sha256(rawBody)
See the API v1 reference for the full signing spec.
4) Read the environment
On each run, start by reading the environment. This tells the agent what's available:
GET /agent-api/v1/workspaces/:workspaceId/environment
GET /agent-api/v1/workspaces/:workspaceId/prompts
GET /agent-api/v1/workspaces/:workspaceId/file-tree
/prompts exposes skills/*.md files as callable capabilities. Read relevant files with:
GET /agent-api/v1/workspaces/:workspaceId/files/:fileNodeId
5) Do the work, then write outputs
Your agent reads sources, applies skills, uses memory, and produces a result. Then it writes:
To create an artifact (direct write, no approval needed):
POST /agent-api/v1/workspaces/:workspaceId/artifacts
{ "title": "Q3 Summary", "text": "# Q3 Executive Summary\n..." }
To propose a file edit (staged for your review):
POST /agent-api/v1/workspaces/:workspaceId/files/:fileNodeId/proposals
{ "content": "...updated memory content..." }
To log activity:
POST /agent-api/v1/workspaces/:workspaceId/events
{ "idempotencyKey": "run-42:done", "eventType": "agent.run.completed", "occurredAt": "..." }
6) Verify what landed
After the run, check artifacts/ in the file tree. Review any pending proposals from the status bar or the Reviews panel.
Spot-check the output against sources. If the result is off, look at the Agent Access scope, operating notes under agents/, and the skills the agent called. Those are the most common sources of drift.