> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devtune.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Authentication

> Create project-scoped API keys, configure endpoint scopes, and authenticate DevTune REST API requests with the Authorization bearer header.

The DevTune API uses API keys for authentication. Each key is scoped to a single project and must be included in the `Authorization` header of every request.

Keys can either:

* keep the default **all scopes** access for that project
* or be narrowed to specific endpoint scopes such as `visibility.read`, `citations.read`, `competitive.read`, `adoption.read`, `traffic.read`, `tests.read`, `actions.read`, `actions.write`, `intelligence.read`, `library.read`, `library.write`, `webhooks.read`, `webhooks.write`, `pages.read`, `audit.read`, `outcomes.read`, `referrals.read`, `agents.read`, and `agents.run`

The ground-truth, Library, Knowledge, and managed-agent scopes are explicit grants. Existing keys are not expanded when these scopes are introduced; edit or replace a key and select the new scope before calling its REST endpoint or MCP tool.

Every key and MCP connection can read its own project's status and usage (`GET /projects/{projectId}/usage` and `devtune_get_project_usage`) without selecting a scope, so an integration can always see whether its project is paused.

`library.read` lists, reads, and searches Library items and reads the Knowledge Profile. `library.write` uploads and manages Library items, applies direct Knowledge Profile edits, and reviews profile proposals. Grant `library.write` only when the integration should be able to add project source material, change agent grounding availability or version links, edit reviewed company context, and approve, dismiss, or restore profile proposals.

## 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 name for the key (e.g., "CI/CD Pipeline" or "BI Dashboard")
5. Select the project the key should access
6. 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:

```
dtk_live_<64 hex characters>
```

For example: `dtk_live_a1b2c3d4e5f6...`

Only the first few characters (`dtk_live_a1b2...`) are stored as a prefix for identification in the dashboard.

## Using Your API Key

Include the key in the `Authorization` header with the `Bearer` prefix:

```bash theme={null}
curl -H "Authorization: Bearer dtk_live_your_key_here" \
  "https://devtune.ai/api/v2/projects/YOUR_PROJECT_ID/visibility/summary"
```

### Example with JavaScript

```javascript theme={null}
const response = await fetch(
  'https://devtune.ai/api/v2/projects/YOUR_PROJECT_ID/visibility/summary',
  {
    headers: {
      Authorization: 'Bearer dtk_live_your_key_here',
    },
  },
);

const { data, meta } = await response.json();
```

### Example with Python

```python theme={null}
import requests

response = requests.get(
    "https://devtune.ai/api/v2/projects/YOUR_PROJECT_ID/visibility/summary",
    headers={"Authorization": "Bearer dtk_live_your_key_here"}
)

result = response.json()
print(result["data"])
```

## MCP OAuth Authentication

The REST API uses API keys. The DevTune MCP server also supports OAuth for MCP clients that can discover and complete an OAuth 2.1 flow.

For OAuth MCP connections, configure the server URL without a project ID:

```
https://devtune.ai/api/mcp
```

The MCP server advertises protected resource metadata at:

```
https://devtune.ai/.well-known/oauth-protected-resource/api/mcp
```

After browser sign-in, DevTune shows a project selector and stores that choice with the OAuth grant. Integration prerequisite: the OAuth access token must include a client identifier claim (`client_id`, `oauth_client_id`, or `azp`), or DevTune rejects MCP authentication. OAuth clients should use standard Supabase OAuth sign-in scopes rather than DevTune API key scopes. OAuth connections run as the signed-in DevTune user for the selected project. Tool access is limited to the capabilities approved for that connection and your current project permissions. Users with DevTune management permission can approve write tools and agent execution. Existing connections do not gain capabilities automatically; see [MCP permissions](/api-reference/mcp-server#available-tools) before reconnecting.

## Key Security

* Keys are hashed with SHA-256 before storage. DevTune never stores the raw key.
* 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.
* 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 supports Cross-Origin Resource Sharing (CORS) for browser-based integrations. Requests from any origin are accepted when a valid API key is provided.

## 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.

## Who Can Manage API Keys

Only team members with the **settings.manage** permission can create or revoke API keys.

## Related Documentation

* **[Rate Limits](/api-reference/rate-limits)** - Request limits by plan tier
* **[Error Handling](/api-reference/errors)** - Common authentication errors


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.