Authenticate and choose the correct permissions
Use bearer tokens with team binding, protocol abilities, roles, and plan checks.
Create tokens in Settings → Account → API Keys while signed in. The key guide covers creation, expiration, one-time token display, and immediate revocation by archiving.
REST requests
Send the token in the Authorization header and request JSON responses. Replace the example origin with your deployed ConversionLab API origin; it is separate from the website/docs origin.
export CONVERSIONLAB_API_ORIGIN='https://api.example.test'
export CONVERSIONLAB_TOKEN='YOUR_REST_TOKEN'
curl --fail-with-body \
"$CONVERSIONLAB_API_ORIGIN/api/projects" \
--header "Authorization: Bearer $CONVERSIONLAB_TOKEN" \
--header 'Accept: application/json'The example hostname and token are placeholders. Store real tokens in your client or server secret configuration rather than browser-delivered code or source control. Bearer API requests do not require the browser's session-login or CSRF-cookie flow.
Abilities and roles
| Key choice in the UI | Stored abilities | Purpose |
|---|---|---|
| REST Read only | read | Safe REST requests |
| REST Read & Write | read, write | Reading and mutating REST requests |
| MCP Read only | mcp:read | Reading through MCP tools |
| MCP Read & Write | mcp:read, mcp:write | Reading and supported MCP mutations |
REST checks read for safe methods and write for mutations; a raw write ability alone is not the REST read ability. Normal UI-created Read & Write keys contain both. MCP accepts its own ability family, and supported mutations require MCP write access.
Token abilities do not grant an underlying user role. The authenticated user's role, project relationships, plan entitlements, and billing state are still enforced. For example, a viewer's write token does not bypass an idea's create policy, and a read-only billing account can block mutations.
Team context
Each token is bound to the team selected when it was created. Tenant data is resolved in that team's context. Supplying another team ID in the request or changing the active browser team does not retarget the token. Create a separate key for another team and use record IDs returned in that team's responses.
Use /api/user to identify the authenticated user. Use /api/projects and relevant project IDs to locate tenant work. Do not treat a globally familiar numeric ID as authorization to read another team's record.
Failed authentication
An expired, revoked, or missing token can return 401. Missing abilities or team access can return 403. A REST write blocked by the team's read-only billing mode returns 402 with error: "subscription_required"; reading remains available. For an unexpected failure, confirm the API origin, token protocol, expiration, archive state, team membership, required role, and billing state before retrying.