Skip to main content
The DevTune API accepts project API keys in the 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 except agents.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.write spends credits when it generates briefs or starts a prompt-set analysis.
  • prompts.write changes what DevTune asks AI platforms, and new prompts count against your plan’s prompt allowance.
  • setup.write changes 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 keeps setup.write so 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 returns 409 with reason project_paused until then.
  • library.write lets the integration add source material, change whether agents can use a Library item, change version links, edit company context and decide profile proposals.
  • agents.review approves 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 need agents.run.
  • agents.write changes what your agents do and when they run, and each scheduled run uses agent credits. It does not start runs; that needs agents.run.
  • agent_picks.run covers everything in Agent Picks that spends credits, and uploading self-runs from the agentpicks CLI.
Each endpoint’s reference page names the scope it requires. An agent can also register itself through auth.md, draft a project setup with the setup.draft scope, and become an API key on a project once a person claims it. See Agent Registration.

Creating an API Key

  1. Navigate to your team account
  2. Open API Keys in the account sidebar
  3. Click Create API Key
  4. Enter a Key Name, such as “CI/CD Pipeline” or “BI Dashboard”
  5. Select the Project the key should access
  6. Choose an Expiration. The default is No expiration
  7. Review the Scopes. Every scope except agents.review is selected by default. Select agents.review only if the integration should approve agent drafts, and clear the scopes it doesn’t need
  8. Click Create API Key
After creation, the full key is displayed once. Copy it immediately and store it securely. You will not be able to view the full key again.

Key Format

API keys follow this format:
For example: dtk_live_a1b2c3d4e5f6... The dashboard identifies each key by its first few characters (dtk_live_a1b2...).

Using Your API Key

Include the key in the Authorization header with the Bearer prefix:
The Quick example shows the response, and the error a key without the scope gets.

Example with JavaScript

Example with Python

CLI OAuth

CLI 0.2.0 and later support devtune 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:
The MCP server advertises protected resource metadata at:
After browser sign-in, DevTune asks for a project and the scopes the connection may use, and stores both with the OAuth grant. OAuth connections run as the signed-in DevTune user for the selected project. Tool access is limited to the scopes approved for that connection and your current project permissions. The person who connects needs the project role a write tool needs: Member for most writes and agent execution, Admin for settings, API keys, webhooks and integrations. Existing connections do not gain scopes automatically; see MCP permissions before reconnecting.

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 Unauthorized response.
  • 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 the X-RateLimit-* response headers, and they can send only the Authorization and Content-Type request headers.

Revoking a Key

To revoke an API key:
  1. Go to API Keys in the account sidebar
  2. Find the key in the list
  3. Click the revoke button (trash icon)
  4. Confirm the revocation
Revoked keys stop working immediately. This action cannot be undone.

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.