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

# Authenticate API requests

> Verify the key, workspace, and scope before connecting your application to Metricanic.

Each public API request carries the token issued for an API key. Metricanic uses that key to identify the workspace and allowed scope, then checks whether the credential is still active and the workspace has the required API access.

Use this flow for server applications and scheduled jobs. A browser session can authenticate tracker requests, but it is not a credential lifecycle for an unattended integration.

## Issue a key for the application

In the tracker, open **API keys** and create a key with a recognizable label. Choose **read** for exports or **write** for supported mutations, then copy the token when it is issued.

The complete lifecycle, including expiry and rotation, is covered in [Manage API keys](/account/api-keys). The key-management routes are panel-only. An existing public API key cannot create a new key for itself.

## Send the token in a header

Store the token in an environment variable or your application's secret store. Send it as a Bearer token:

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

For a key labeled `daily-report-export`, a successful response has this shape:

```json theme={null}
{
	"ok": true,
	"data": {
		"tenantId": "YOUR_WORKSPACE_ID",
		"provider": "api-key",
		"scope": "read",
		"keyId": "YOUR_KEY_ID",
		"label": "daily-report-export"
	}
}
```

Check the workspace and scope before proceeding. A valid token for the wrong workspace can successfully return a different set of campaigns. The `keyId` is an identifier for managing the key, not a replacement for the token in the header.

## Choose read or write deliberately

A **read** key allows reads. A **write** key also allows the public create, update, archive, and restore operations documented in this reference.

For example, a report exporter should keep **read** even if it runs every hour. Frequency does not require additional permission. A provisioning service that creates campaigns needs **write**, and should verify the returned entity IDs before using them in further writes.

Requests act inside the key's workspace. Supplying another workspace's entity ID does not grant access to that entity. Public keys also do not unlock internal account, billing, or credential routes.

## Distinguish authentication from access

| Response                   | What to check first                                                                                |
| -------------------------- | -------------------------------------------------------------------------------------------------- |
| `401 UNAUTHORIZED`         | The complete token was copied, the Bearer header is present, and the key is not expired or revoked |
| `402 BILLING_REQUIRED`     | The workspace currently has the subscription access required for public API keys                   |
| `403 FORBIDDEN` on a write | The key has write scope and the request is allowed                                                 |
| `404 NOT_FOUND`            | The method and route are public, and the entity belongs to this workspace                          |

Do not replace a working key to solve a missing entity or invalid report filter. Run `whoami` first to separate credential problems from endpoint problems.

For an uninterrupted planned replacement, create a second key, switch the application, verify it, then revoke the first. **Rotate** stops the old token immediately. If a credential is exposed, revoke it and issue a replacement.

Keep the token out of query strings, browser scripts, and application logs. The product MCP uses its own [OAuth connection](/integrations/ai-agents), so connecting Claude does not require sharing this token.