Authentication

The DraftLift API uses API keys for authentication. Keys carry scopes (what they can do) and an optional workspace binding (which workspace they operate against). Both are chosen at creation time and cannot be changed after issue — re-issue the key to change them.

Creating an API key

Navigate to Settings → API Keys in your DraftLift dashboard.
Click Create API Key and give it a descriptive name.
Pick scopes (Read is always included; Write is on by default).
Pick a workspace binding (or leave it as All workspaces).
Pick an expiration: 30 days, 90 days (default), 365 days, or Never.
Copy the key immediately — it is only shown once.

If your account has exactly one workspace, the workspace picker is hidden and the key binds to that workspace automatically.

API key format

dl_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Keys always start with dl_live_ for easy identification.

Using your key

Include the key in the Authorization header:

Authorization: Bearer dl_live_your_key_here

You can also set DRAFTLIFT_API_KEY in your environment — the CLI prefers it over the saved credentials file:

export DRAFTLIFT_API_KEY=dl_live_your_key_here

Scopes

Scope	What it allows
`read`	Every `GET` endpoint (list, get, search).
`write`	Everything `read` allows, plus create, update, delete, and generate.

Scopes are additive. The default for newly issued keys is ["read", "write"]. The admin scope is reserved in the schema but is not surfaced in v1; admin endpoints stay JWT-only. A scope-gated mutation called with a read-only key returns:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "FORBIDDEN",
  "message": "This endpoint requires the 'write' scope.",
  "details": {
    "error_code": "insufficient_scope",
    "required_scope": "write",
    "current_scopes": ["read"],
    "upgrade_action": "Re-issue your API key with the required scope at https://app.draftliftai.com/settings/api-keys"
  },
  "trace_id": "tr_..."
}

The CLI maps this to exit code 2 and prints the upgrade_action URL on its own line.

Workspace binding

Workspaces partition references, memories, content calendars, and generated drafts. When you create a key, you choose one of two postures:

Posture	When to use
All workspaces	Multi-workspace agents, CLI on a laptop, anything that operates across workspaces.
Bound to a workspace	Per-client keys, scoped CI tokens, or any key you want to silently lock to one workspace’s data.

Behavior at request time

Request	Outcome
Unbound key, no `workspace_id`	Endpoints that require a workspace return `400` (or operate on the default).
Unbound key, explicit `workspace_id`	Operates on the requested workspace.
Bound key, no `workspace_id`	Server injects the bound workspace automatically.
Bound key, `workspace_id` matches the binding	200 OK.
Bound key, `workspace_id` differs from the binding	`403 workspace_mismatch` — the server never silently overrides.

Mismatch errors

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "FORBIDDEN",
  "message": "This API key is bound to a specific workspace.",
  "details": {
    "error_code": "workspace_mismatch",
    "bound_workspace_id": "ws_aaa...",
    "requested_workspace_id": "ws_bbb..."
  },
  "trace_id": "tr_..."
}

For a deeper guide on choosing scopes and binding, see API Key Scopes & Workspace Binding.

Introspecting a key

curl -H "Authorization: Bearer dl_live_..." \
  https://draftliftai.com/api/v1/api-keys/current

Returns the calling key’s name, scopes, workspace_id, expires_at, and last_used_at. This is the only /api-keys/* endpoint that accepts API keys — every other key-management operation requires a web session.

Endpoints not callable with API keys (denylist)

Some operations require an interactive web session and cannot be performed with a dl_live_ key:

POST /api-keys, DELETE /api-keys/:id, PUT /api-keys/:id — creating, revoking, or renaming keys.
/billing/* mutations — checkout, portal sessions, refunds, cancel subscription.
/admin/* — every admin endpoint.
PUT /me/settings, PUT /learning-preferences, account/profile mutations.
Auth flows: /auth/login, /cli-auth/*, OAuth callbacks.

Calling these with a Bearer key returns 401 Unauthorized. Use the dashboard for these operations.

Stability and versioning

Endpoints are tagged in the OpenAPI spec:

stable — Stable. Breaking changes will require a /api/v2/... mount.
beta — Functional but the response shape may evolve. New fields are additive; we will not remove or rename fields without a deprecation cycle.
internal — Excluded from public docs. Do not depend on these.

Newly dual-auth routes (everything outside /templates, /generate, /finalizeContent, /thesis, /mcp) ship as beta until they have ~30 days of stable use without schema changes.

Key management

Revoke a key from Settings → API Keys — takes effect within seconds.
Rename keys to keep them organized.
Monitor usage per key from the Settings page.
Rotate by creating a replacement, rolling it into your config, then revoking the old key.

Requirements

API access requires a Business or Agency plan. Starter and Pro users see an upgrade prompt on the API Keys settings tab.

API Reference

Generation

Contents

Templates

Memories

Memory Categories

Models

Reference Materials

Workspaces

Usage

Images

Conversions

Voice Profiles

Knowledge Graph

Content (Beta)

Account

Authentication

Authentication

Creating an API key

API key format

Using your key

Scopes

Workspace binding

Behavior at request time

Mismatch errors

Introspecting a key

Endpoints not callable with API keys (denylist)

Stability and versioning

Key management

Requirements

​Authentication

​Creating an API key

​API key format

​Using your key

​Scopes

​Workspace binding

​Behavior at request time

​Mismatch errors

​Introspecting a key

​Endpoints not callable with API keys (denylist)

​Stability and versioning

​Key management

​Requirements

Authentication

Creating an API key

API key format

Using your key

Scopes

Workspace binding

Behavior at request time

Mismatch errors

Introspecting a key

Endpoints not callable with API keys (denylist)

Stability and versioning

Key management

Requirements