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

# Manage API keys

> Give each integration its own scoped credential, verify it, and replace it without losing access unexpectedly.

An API key lets your software call Metricanic without a browser session. Use one for a scheduled report export, a private dashboard, or an application that manages supported tracking entities.

Create a separate key for each integration so its name and last-use information help you identify it, and you can revoke one application without disrupting the others. Public API key creation and use require eligible Pro or Scale access.

## Choose the smallest useful scope

| Scope     | Use it for                                                            | What it allows                                        |
| --------- | --------------------------------------------------------------------- | ----------------------------------------------------- |
| **read**  | Reporting exports, monitoring, analysis                               | Read operations on the public API                     |
| **write** | Software that creates, edits, archives, or restores tracking entities | Read and supported write operations on the public API |

A write key does not turn every internal tracker route into a public API. The available operations are listed in the [API reference](/api-reference/introduction). Key management itself requires your signed-in tracker session.

## Create and verify a key

1. Open **API keys** in the account area and click **Create key**.
2. Set **Label** to the application's purpose, such as `daily-report-export`.
3. Choose **Scope**. Keep **read** for the report export example.
4. Set **Expires in** to 30, 90, or 180 days. Choose a lifetime you can maintain before expiry.
5. Click **Create key** and copy the token immediately. It is displayed only when issued.
6. Store it in your application's server-side secret configuration, then verify it:

```bash theme={null}
curl 'https://panel.metricanic.com/api/v1/whoami' \
  -H "Authorization: Bearer $METRICANIC_API_KEY"
```

The response should have `ok: true`, `data.provider: "api-key"`, and the expected `data.scope`. Confirm the key label and workspace before connecting a write-capable application.

Use the copied token in the `Authorization` header. The key ID displayed in the account page identifies the credential for management. It is not the token to send in requests.

## Replace a key during planned maintenance

For an application that must keep running, create a second key with the same needed scope. Deploy the new secret, verify a successful API call, then revoke the old key.

**Rotate** is useful when you want an immediate replacement. It issues a new token and stops the old one from working immediately. The panel's rotation preserves the scope and remaining expiration period. It does not start another full 30, 90, or 180 days.

If the old token may have been exposed, use **Revoke** immediately and replace it in the application. Revocation is available independently of permission to create another key.

## Diagnose a stopped integration

An expired, revoked, or incorrectly copied token produces an authentication failure. A read key cannot perform writes. A valid key can also be blocked if the workspace no longer has the required subscription access.

Start by calling `whoami` from the same environment as the failing application. If that works, inspect the endpoint, method, and response code using [API errors](/api-reference/errors). If it fails, check the key's expiry, scope, and subscription before changing the application logic.

Keep tokens on your server. Browser-side code would expose them to anyone who can inspect the page. AI agents use a separate [MCP authorization flow](/integrations/ai-agents).