Authorization header. CLI 0.2.0 and later also support browser sign-in for their supported operations; see CLI OAuth.
Scopes
A new key has every scope for its project selected by default exceptagents.review, which you select yourself. You can narrow it to the scopes below. A key can only call the REST endpoints and MCP tools its scopes cover.
Every key and MCP connection can read its own project’s status and usage (
GET /projects/{projectId}/usage) and its connection context (GET /projects/{projectId}/connection) without a scope. Use them to see whether the project is paused, which project the credential is bound to, and which scopes and features it can use now.
Existing keys and MCP connections never gain a scope added later. Edit or replace the key and select the scope, or revoke the MCP client’s OAuth authorization and connect again to approve it, before calling its endpoint or MCP tool.
Some write operations also require the key’s creator to keep the project role the change needs. Each endpoint documents its requirements. Grant write scopes only when the integration should make that change:
actions.writespends credits when it generates briefs or starts a prompt-set analysis.prompts.writechanges what DevTune asks AI platforms, and new prompts count against your plan’s prompt allowance.setup.writechanges whose citations and mentions DevTune counts from that day on. Archiving a competitor stops tracking it and keeps its recorded history; restoring it resumes tracking from then. Pausing needs the Agency plan, and resuming needs a free project slot and room in the prompt allowance. A paused project keepssetup.writeso the key can resume it. Disconnecting GA4 and adding, switching and removing content sources also work while paused, as in the app; every other setup change returns409with reasonproject_pauseduntil then.library.writelets the integration add source material, change whether agents can use a Library item, change version links, edit company context and decide profile proposals.agents.reviewapproves agent drafts, which adds action and brief drafts to Actions, or dismisses them, which discards them. It does not start runs or send follow-ups; those needagents.run.agents.writechanges what your agents do and when they run, and each scheduled run uses agent credits. It does not start runs; that needsagents.run.agent_picks.runcovers everything in Agent Picks that spends credits, and uploading self-runs from theagentpicksCLI.
setup.draft scope, and become an API key on a project once a person claims it. See Agent Registration.
Creating an API Key
- Navigate to your team account
- Open API Keys in the account sidebar
- Click Create API Key
- Enter a Key Name, such as “CI/CD Pipeline” or “BI Dashboard”
- Select the Project the key should access
- Choose an Expiration. The default is No expiration
- Review the Scopes. Every scope except
agents.reviewis selected by default. Selectagents.reviewonly if the integration should approve agent drafts, and clear the scopes it doesn’t need - Click Create API Key
Key Format
API keys follow this format:dtk_live_a1b2c3d4e5f6...
The dashboard identifies each key by its first few characters (dtk_live_a1b2...).
Using Your API Key
Include the key in theAuthorization header with the Bearer prefix:
Example with JavaScript
Example with Python
CLI OAuth
CLI 0.2.0 and later supportdevtune login using the same
browser consent and project grants as MCP. CLI 0.1.x requires a project API key.
OAuth REST access is limited to discovering the connected project, reading citation
stats, reading traffic summaries, reading the outcomes ledger, listing Actions and
changing their status, reading Action briefs and drafts, listing topics, creating
prompts, creating and deleting webhooks, reading response history and individual responses,
reading brand sentiment, listing managed agents, launching agents and checking run
status, creating, editing, archiving and restoring custom agents, and turning agent
schedules on, changing them or turning them off. Other REST endpoints continue to require an API key.
GET /api/v2/connection discovers only the credential’s bound project and returns
the same context as GET /api/v2/projects/{projectId}/connection and the MCP
devtune_get_connection_context tool. OAuth requests revalidate consent, current
membership, scopes and API access on every request; they are never cached.
Discovery is at
https://devtune.ai/.well-known/oauth-protected-resource/api/v2.
MCP OAuth Authentication
The DevTune MCP server supports OAuth for MCP clients that can discover and complete an OAuth 2.1 flow. It shares browser consent and project grants with the CLI. For OAuth MCP connections, configure the server URL without a project ID:Custom OAuth clients
If you build your own MCP OAuth client, the access token must include a client identifier claim (client_id, oauth_client_id or azp), or DevTune rejects MCP authentication. Request standard Supabase OAuth sign-in scopes, not DevTune API key scopes.
Key Security
- DevTune never stores the raw key, so a lost key cannot be recovered. Revoke it and create another.
- Each key is scoped to exactly one project. It cannot access data from other projects.
- Each key stores an explicit scope set. It can only call endpoints and MCP tools covered by those configured scopes.
- Requests with an invalid, expired, or revoked key receive a generic
401 Unauthorizedresponse. - A key works while its creator holds Viewer or higher on the key’s project or owns its personal account. If the creator loses access or their DevTune user is deleted, requests return
401 Unauthorized. Restoring the project role lets the same key work again. - A key also stops working while its creator is suspended from DevTune. It works again when the suspension ends if the creator still has project access.
- Requests with a valid key that lacks the required endpoint or MCP tool scope receive
403 Forbidden, so permission errors stay distinct from authentication failures.
CORS Support
The API accepts requests from any origin when a valid API key is provided. Call it from a server, not from browser code: a key in browser code is readable by anyone who loads the page. If you need data in a browser, proxy the request through your own server. Browser calls also have two limits. They can’t read theX-RateLimit-* response headers, and they can send only the Authorization and Content-Type request headers.
Revoking a Key
To revoke an API key:- Go to API Keys in the account sidebar
- Find the key in the list
- Click the revoke button (trash icon)
- Confirm the revocation
Revoking a key from the key itself
An agent can revoke the API key it calls with, without a person signing in:DELETE /api/v2/projects/{projectId}/connection/key (MCP: devtune_revoke_api_key). Later requests with the key get 401.
It needs only project.read, which every API key holds, and never acts on another key. It works while the project is paused. Called with a claimed agent’s dtk_agent_ token, it revokes the key the claim created: the token stops working, exchanging the assertion again returns invalid_grant, and the agent must register again, or, from another connection with setup.write, draft the project again. An OAuth connection is refused with 403 (not_an_api_key); disconnect it from its client. With Hide revoked off, Settings > API keys shows the key as Revoked, without naming who revoked it. It is not available in code mode.
Rotating a key from the key itself
An agent can replace the secret of the API key it calls with, without a person signing in:POST /api/v2/projects/{projectId}/connection/key/rotate (MCP: devtune_rotate_api_key). The key keeps its id, name, scopes and expiry, and Settings > API keys shows the same key with a new prefix. Only the secret changes, and the new one is in the response once.
The old secret stops working in the same step, with no grace period. Store the new secret before anything else. If the response is lost, no working secret is left: a person must create a new key in Settings > API keys.
It needs only project.read, which every API key holds, and never acts on another key. It works while the project is paused. A valid key returns 403 (creator_cannot_create) if its creator lacks Admin on the key’s project. A claimed agent’s dtk_agent_ token is refused with 403 (agent_token), and an OAuth connection with 403 (not_an_api_key). If the key is revoked, rotated, deleted or expires while this request runs, it returns 409 (key_unavailable). A key that’s already revoked or expired gets 401. A refusal changes nothing. Rotating doesn’t reset the key’s rate limit, but requests already in flight during the rotation count against the old secret. It is not available in code mode.
Who Can Manage API Keys
Project Admins can create and revoke API keys. A key can also revoke itself. Self-rotation requires the key’s creator to be a project Admin.Related Documentation
- Rate Limits - Request limits by plan tier
- Error Handling - Common authentication errors