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

# Authentication

> Create and manage Optimaze API keys for programmatic access, including business metrics ingest.

Optimaze API keys let external systems authenticate to Optimaze APIs without a user login. Keys are organisation-scoped, support fine-grained scopes, and can be rotated or revoked at any time.

Use API keys to send [business metrics](https://docs.optimazehq.com/business-metrics.md) and other programmatic data into Optimaze.

## Prerequisites

* **Organisation admin** role in Optimaze (required to create, rotate, and revoke keys)
* Access to **Integrations** in the dashboard

## Create an API key

### Step 1: Open the API key wizard

In Optimaze, under **Data**, select **Integrations**, then select **Create API key** on the **Optimaze API** tile.

Alternatively, open **Integrations** → **API keys** and choose **Create API key**.

![API keys — Integrations connect catalog](https://mintcdn.com/optimaze/H22rTqPFmthmkajv/images/image-apikey1.png?fit=max\&auto=format\&n=H22rTqPFmthmkajv\&q=85\&s=68a9c348bd13fe1efe2c68e4a0d57311)

### Step 2: Enter key details

Provide a descriptive **name** (for example `Finance warehouse ingest` or `CI metrics publisher`). Names appear in the API keys list and audit views.

![API keys — key details step](https://mintcdn.com/optimaze/H22rTqPFmthmkajv/images/image-apikey2.png?fit=max\&auto=format\&n=H22rTqPFmthmkajv\&q=85\&s=8892310950b2fe3aaf61b97aa9b711b9)

### Step 3: Select scopes

Choose the scopes this key needs. For [business metrics ingest](https://docs.optimazehq.com/business-metrics.md), select **`metrics:ingest`**.

| Scope | Access |
| :- | :- |
| `metrics:ingest` | Post datapoints to `POST /v1/metrics/ingest` |

![API keys — permissions step](https://mintcdn.com/optimaze/H22rTqPFmthmkajv/images/image-apikey3.png?fit=max\&auto=format\&n=H22rTqPFmthmkajv\&q=85\&s=66fa54ab2617746c29c0daaa11ca7171)

### Step 4: Review and copy the secret

Review the key name and scopes, then create the key. Optimaze shows the **raw secret once** (format `omz_...`). Copy and store it in your secrets manager, it cannot be retrieved again.

![API keys — secret shown once](https://mintcdn.com/optimaze/H22rTqPFmthmkajv/images/image-apikey4.png?fit=max\&auto=format\&n=H22rTqPFmthmkajv\&q=85\&s=0bfcefbafea00e599eacee1cd80dcae0)

## Use the key

Pass the raw key in the **`optimaze-api-key`** header on API requests. Also send **`optimaze-org-id`** when the endpoint requires organisation context (for example business metrics ingest).

See [Business metrics](https://docs.optimazehq.com/business-metrics.md) for a complete ingest example.

## Manage existing keys

From **Integrations** → **API keys**, organisation admins can:

* **List** all keys in the organisation (members see only keys they created)
* **Rotate** a key: issues a new secret; optionally keep the old key active during a grace period
* **Revoke** a key: immediately blocks further use

Rotated and revoked keys stop authenticating new requests. Update integrations with the new secret after rotation.

## Security practices

* Store keys in a secrets manager, not source control
* Grant the minimum scopes required (`metrics:ingest` only when ingesting metrics)
* Rotate keys on a schedule or when team members with access leave
* Revoke unused or compromised keys promptly

## Troubleshooting

* **Cannot create a key:** Confirm you have organisation admin permissions.
* **401 / 403 on API calls:** Key may be revoked, expired, missing the required scope, or paired with the wrong `optimaze-org-id`.
* **Lost secret:** Rotate or revoke the key and create a new one; raw secrets are not stored server-side.


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