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

# API keys

> Create, review and revoke the workspace API keys your own systems use to call Mercora.

An API key lets one of your own systems, such as an ERP or an internal script, call the [Mercora API](https://docs.mercora.io/api-reference/introduction.md) on behalf of your workspace. This page shows you how to create, review and revoke keys.

> [!NOTE]
>
> **Before you start:** only workspace admins manage keys, under **Settings → API** in the **Administration** section.

There is no separate switch to turn the API on. A workspace with no active key can't be called, and revoking a key cuts it off at once.

> [!TIP]
>
> Create one key per calling system and name it after that system. Then you can see when each system last called Mercora, and revoke one without affecting the others.

## The API page

**Settings → API** has two sections.

**Connection** shows what a developer needs to connect:

* **Base URL**: your workspace's API address.
* **Authentication**: the header to send on every request, `Authorization: Bearer <key>`.
* **API reference**: links to an interactive reference (**Swagger UI**) and the machine-readable **openapi.json**.

**API keys** lists every key, active and revoked, and is where you create new ones.

![The API keys section of Settings → API](https://mintcdn.com/placeholder-f4ffdeec/22McaegbdDRSI41b/images/admin/api-keys.png?fit=max\&auto=format\&n=22McaegbdDRSI41b\&q=85\&s=45bc12a2e8e1b3d38f57b53dff4d6182)

The API keys section before any key exists: name the key, keep or untick its scopes, then click Create key. Each scope lists the endpoints it opens.

## Scopes

A key can only call what its scopes allow. You choose the scopes when you create the key.

| Scope | What it allows |
| - | - |
| **Hedge requests** | Read the hedge books and positions, send hedge requests into the Inbox, and check where they stand. |
| **Automations** | Start runs of automations that are set to run from the API. Anything a run would change still waits for a person in Mercora. |

Under each scope, the page lists the endpoints it opens.

A key never gains a scope it wasn't given. If Mercora adds a new scope later, your existing keys don't get it: create a new key that includes it.

> [!NOTE]
>
> Some calls also need a module. Sending a hedge request needs the **Hedging** module, and starting or continuing an automation run needs the **Automations** module. While the module is off, those calls are refused. Ask your workspace admin.

## Create a key

**1. Open the API page**

Go to **Settings → API**.

**2. Name the key**

In the **API keys** section, enter a name for the key, for example "Origin ERP". Names can be up to 80 characters.

**3. Choose its scopes**

Every scope is ticked to start with. Untick anything this system shouldn't reach. A key needs at least one scope.

**4. Click Create key**

The button becomes available once the key has a name and at least one scope. Mercora creates the key and shows it once.

**5. Copy the key**

Copy the key with the copy button and store it somewhere safe, such as your password manager or your system's secret store. Click **Done** when you have it.

> [!WARNING]
>
> The key is shown only once. Mercora keeps only a fingerprint of it, so it can't show you the key again. If you lose it, revoke it and create a new one.

Keys start with `mk_`. Treat a key like a password: anyone who has it can call Mercora as your workspace, within its scopes.

## Review your keys

Each key in the list shows:

* Its name, and an **Active** or **Revoked** badge.
* The first characters of the key, so you can tell keys apart.
* Its scopes.
* When it was created.
* When it was last used, or **Never used**.
* When it was revoked, if it has been.

Active keys are listed first.

## Revoke a key

Revoke a key when the system that uses it is retired, or if you think the key has been exposed.

**1. Find the key**

Go to **Settings → API** and find the key in the **API keys** list.

**2. Click Revoke**

Click **Revoke** next to it.

**3. Confirm**

Click **Revoke** again to confirm. Requests sent with the key fail from then on.

Revoking can't be undone. The key stays in the list, marked **Revoked**, so you keep a record of it. To restore access, create a new key and give it to the system.

## Next steps

> **[API introduction](https://docs.mercora.io/api-reference/introduction.md)**
>
> Base URL, authentication, errors and idempotency.

> **[Hedging](https://docs.mercora.io/workflows/hedging.md)**
>
> How hedge requests are reviewed and sent from the Inbox.

> **[Automations](https://docs.mercora.io/workflows/automations.md)**
>
> Set an automation to run from the API.


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