Get started

Authentication

Every interface — REST, MCP, and OAuth — resolves to the same authorization model. Requests authenticate with an API key or a signed-in session, and are checked against explicit scopes.

API keys

Send Authorization: Bearer dsk_…. Workspace-scoped, hashed at rest, shown once.

Session

Signed-in browser sessions authenticate automatically and resolve to your capabilities.

Preview

Delegated OAuth

Act on behalf of users with per-user scopes. See OAuth.

How API keys work

Create and manage keys from API Keys. Here's the full lifecycle, exactly as implemented today.

CreateSign in, then create a key with a name and the scopes it needs. Creating keys requires workspace admin or owner, plus multi-factor authentication if your account has it enabled.
Copy onceThe full key (prefixed dsk_) is shown a single time at creation and cannot be retrieved again. Copy it immediately and store it securely.
AuthenticateSend the key as a Bearer token in the Authorization header on every request.
Expiry (optional)A key can carry an optional expiry date. After it passes, requests return 401 api_key_expired.
RevokeRevoke a key at any time. Revocation is immediate — requests with a revoked key return 401.
RotateThere is no in-place rotation. To rotate, create a new key, migrate your integration, then revoke the old one.
HTTP header
Authorization: Bearer dsk_live_••••••••••••••••

Store keys securely

Keep keys in an environment variable or secret manager — never in client-side code or version control. If a key is exposed, revoke it and create a new one.

Scopes

API keys carry explicit scopes. A request with an insufficient scope returns 403 scope_insufficient. Grant the minimum a key needs. Scopes marked write can modify data.

Scopes are capability gates, not resource visibility grants

Scopes grant permission to use an API capability. They do not grant visibility to every resource in the account. Results remain bounded by the authenticated principal's account, user, project, workspace, team, and engagement visibility.

Documents & content

documents:read

List and retrieve documents, packages, versions, and metadata.

read
documents:write

Create, update, and delete documents and their metadata.

write
content:read

Read raw document content blocks and structured content trees.

read
content:write

Reserved: modify document content blocks and structured content trees. No public operation is gated by this scope yet; it is not grantable until a content-write API ships.

write
assets:read

Reserved: list and download document assets. No public operation is gated by this scope yet; it is not grantable until an assets API ships.

read
assets:write

Reserved: upload, replace, and delete document assets. No public operation is gated by this scope yet; it is not grantable until an assets API ships.

write
comments:read

List and read comment threads and suggestions.

read
comments:write

Create, edit, and resolve comment threads and suggestions.

write
search:read

Search documents, content, and metadata across the workspace.

read
analytics:read

Access document engagement and usage analytics.

read

Workflow

workflow:read

Read document workflow state, available transitions, and approval history.

read
workflow:write

Trigger workflow transitions and submit approvals.

write

Exports

exports:read

Export documents to PDF, DOCX, and Markdown formats.

read

Projects

engagements:read

Customer and commercial-engagement identity, hierarchy, status, and engagement-project links (read-only). No financials, rates, or contract terms.

read
project-health:write

Acknowledge advisory Project Health alerts through confirmed, idempotent commands.

write
financials:read

Read project financial health: budget, margin, burn rate, and forecasts. Equivalent to the revops:view_margin session permission.

read
staffing:read

Read project staffing status: role coverage, discipline gaps, open requests, and delivery risk signals. Equivalent to the revops:view_capacity session permission.

read
agent:read

Read agent-optimized project delivery, sprint, and risk read models via the Agent API (/api/agent/v1). Directional signals only — no rates, invoice data, or personal metadata.

read
context-opportunity:write

Record a Context Opportunity — an evidence-backed, advisory proposal that some governed domain may warrant an action. Never approves, mutates, or promotes governed truth; creates ONLY an opportunity record.

write
delivery-timeline:read

Read governed delivery milestones, workstreams, and timeline geometry without moving execution coordinates.

read
delivery-timeline:write

Run explicit milestone status, target-date, and progress commands through the governed Delivery command path.

write
estimates:read

Read project-scoped estimates, effort, role demand, scope, immutable versions, and comparisons.

read
estimates:write

Create estimates, update bounded draft metadata, and persist reviewable estimate change proposals.

write
estimates:operate

Request human baseline review or explicitly freeze an immutable estimate baseline.

write

Work items

sprints:read

Read sprint planning context, readiness, reports, and proposal-only planning suggestions. Does not apply plans or move work.

read
work-items:comment

Create and edit authorized work-item comments, including provider writeback when the source owns comments.

write
work-items:transition

Apply valid Execute or provider-backed workflow transitions with audit history.

write
work-items:assign

Assign, reassign, or unassign eligible owners without granting staffing or capacity authority.

write
work-items:schedule

Set or clear governed date and sprint placement fields through the Execute command boundary.

write
work-items:estimate

Set or clear points/estimate fields without exposing commercial rates, margins, or subscription data.

write
work-items:link

Manage labels and normalized work-item relationships such as dependencies, related, duplicates, and parent/child links.

write
work-items:blockers

Raise, update, transition, and resolve blockers linked to work items.

write
work-items:focus

Pin, annotate, reprioritize, snooze, or clear work items in governed focus views.

write
work-items:bulk

Run bounded, confirmation-required bulk operations across authorized work items.

write
work-item-enhance:run

Create proposal-first Work Item Enhance runs and execute bounded enhancement actions.

write
work-item-enhance:apply

Apply selected Work Item Enhance drafts back to authorized canonical work-item fields.

write
work-item-enhance:code-context

Inspect authorized repository/code context for Work Item Enhance implementation planning without writing code.

read

Revenue operations

opportunities:read

List and retrieve revenue opportunities and delivery forecasts.

read

Audit

audit:read

Read the account-level audit event stream. Requires an Enterprise plan and the audit:account.view session permission. Equivalent to viewing the account audit dashboard.

read

Webhooks

webhooks:manage

Create, update, delete, and inspect webhook registrations.

write

Time management

time:read_self

Read the authenticated user's time entries and time-management state.

read
time:write_self

Create and change explicit time entries for the authenticated user. Inferred time remains proposal-only.

write
time:submit_self

Submit or recall the authenticated user's reviewed work day. Never grants approval authority.

write
time:read_team

Read only time submissions the authenticated user is eligible to review in the active workspace.

read
time:approve_team

Approve or reject time submissions where the authenticated user is an eligible approver.

write
time:import

Start provider-backed time import runs for the authenticated user with immutable source identity.

write
time:reconcile

Read and resolve authorized provider reconciliation findings without changing provider authority.

write

Admin

admin

Wildcard over every scope-gated operation — equivalent to holding every scope. Deliberately does NOT satisfy capability-gated routes (financial health, staffing status, audit log, delivery forecast): those require session authentication regardless of key scopes. Use with care.

write

Rate limits

Limits are applied per API key — and, identically, per workspace and delegated-OAuth principal for OAuth-authenticated requests (REST, GraphQL, and MCP all share the same underlying check, so none of them get more headroom than an API key would). Every response includes these headers; a 429 rate_limit_exceeded is returned when exceeded.

X-RateLimit-Limit

Total requests allowed in the window

X-RateLimit-Remaining

Requests remaining in the current window

X-RateLimit-Reset

Unix timestamp when the window resets

Retry-After

Seconds to wait before retrying (only on 429)

Errors

Errors share a consistent JSON envelope with a stable code, a human-readable message, and the HTTP status.

401missing_auth

No API key or session was provided.

Fix: Add an Authorization: Bearer <key> header.

401invalid_api_key

The key is malformed, unknown, or revoked.

Fix: Check the key value, or create a new one in API Keys.

401api_key_expired

The key is past its expiry date.

Fix: Create a new key and update your integration.

403scope_insufficient

The key lacks the scope the endpoint requires.

Fix: Grant the required scope (shown on each endpoint) to a key.

400bad_request

A required field is missing or has the wrong type.

Fix: Check the request body against the endpoint reference.

404not_found

The resource does not exist or is outside your workspace.

Fix: Verify the id and that it belongs to your workspace.

429rate_limit_exceeded

Too many requests in the current window.

Fix: Honor the Retry-After header and back off exponentially.

500internal_error

An unexpected error occurred on our side.

Fix: Retry with backoff; contact support if it persists.

Each endpoint in the API reference also lists the specific errors it can return.