> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/settings/managing-api-access-keys.md).

# Managing API Keys

Create, rotate, deactivate and delete API keys, and choose the permissions each key holds.

API keys let external systems call Harmony without a person signing in: your own scripts, an automation platform, a webhook that starts an agent, or a Bring Your Own App push. Each key belongs to your workspace and carries its own permissions.

This article explains how API keys work, how to create one, and how to manage it afterwards.

### How API Keys Work

* **A key holds its own permissions.** A key holds permission sets, the same kind you give to a group. Harmony authorizes every request against those sets and nothing else. The permissions of the person who created the key play no part.
* **A key acts on behalf of its creator.** Changes a key makes, such as updating a ticket or assigning an application owner, appear in activity history under the person who created it. The **Created by** column shows who that is.
* **A key is tied to one tenant.** You never send a tenant identifier with a request.
* **A key can expire.** Pick an expiration when you create it. After that date the key stops working.

{% hint style="warning" %}
If the person who created a key leaves the company, Harmony deactivates the key permanently when their employee record is terminated or deleted. Create a replacement key from another account and update the integration before that happens.
{% endhint %}

### Who Can Manage API Keys

API keys live in **Settings → Authorization & Permissions**, on the **API keys** tab.

| Access                                               | What it allows                               |
| ---------------------------------------------------- | -------------------------------------------- |
| **Viewer** on the **Permissions** row under Settings | See the API keys tab and every key's details |
| **Admin** on the **Permissions** row under Settings  | Create, rotate, deactivate and delete keys   |

### Before You Create a Key: Choose Its Permissions

Give the key only the permission sets the integration needs:

* **A built-in set**, such as **Platform Observer** for a read-only reporting script.
* **A custom set** for anything more specific. Create it on the **Permissions** tab first; see [Managing Authorization and Permissions](https://docs.harmony.io/settings/managing-authorization-and-permissions.md#create-a-custom-permission-set).

Some actions are **capabilities**, switches that sit under a module's row in the permission set and are separate from its access level:

| Capability         | Where  | What it allows                                                                                                               |
| ------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------- |
| **Trigger agents** | Agents | Start agents through their triggers, such as an incoming webhook. A set can hold it without any access to the Agents module. |

Common choices:

| Integration                                      | Permissions the key needs                                                                                                                                                  |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Read data through the Harmony API                | **Viewer** on the modules it reads, for example a built-in Observer set                                                                                                    |
| Create or update records through the Harmony API | **Editor** on the modules it changes                                                                                                                                       |
| Call an agent's webhook                          | **Trigger agents** under Agents. See [Using Webhook Triggers](https://docs.harmony.io/workflows-and-automation/building-and-managing-workflows.md#using-webhook-triggers). |
| Push users and usage with Bring Your Own App     | See [Bring Your Own App](https://docs.harmony.io/integrations/saas-applications/bring-your-own-app#prerequisites)                                                          |

### Creating an API Key

1. Open **Settings → Authorization & Permissions** and select the **API keys** tab.
2. Click **Create key**.
3. Enter a **Name** that says what the key is for, for example `Zapier Integration` or `Reporting script`. Letters, numbers, single spaces, hyphens, underscores and periods are allowed.
4. Choose the **Permission set**. The key gets the same permissions as the selected set.
5. Choose an **Expiration**: 30 days (the default), 60 days, 90 days, 6 months, 1 year or Never.
6. Optionally add a **Description**.
7. Click **Continue**.
8. Copy the **Value** and store it where your integration can read it, such as a secrets manager.

{% hint style="danger" %}
The key value is shown only once. It cannot be displayed again after you close the dialog. If you lose it, rotate the key to get a new value.
{% endhint %}

### Using an API Key

How you send the key depends on where the request goes:

| Destination                                                          | Header                                    |
| -------------------------------------------------------------------- | ----------------------------------------- |
| The Harmony API, `https://api.harmony.io`                            | `Authorization: AccessKey <your-api-key>` |
| Agent webhooks and Bring Your Own App, `https://external.harmony.io` | `Authorization: Bearer <your-api-key>`    |

See the [API reference](https://docs.harmony.io/api-references#authentication) for a first request.

### Viewing Your API Keys

The API keys tab lists every key in the workspace:

| Column          | What it shows                                                                                   |
| --------------- | ----------------------------------------------------------------------------------------------- |
| **Name**        | The key's name, with its description underneath                                                 |
| **Status**      | **Active**, **Expiring soon** (7 days or less left), **Expired** or **Deactivated**             |
| **Permissions** | The permission sets the key holds                                                               |
| **Expiration**  | The expiry date, or **Never**                                                                   |
| **Created by**  | The person the key acts on behalf of. Keys Harmony created for an integration show **Harmony**. |
| **Last used**   | When the key last made a request. Updated about once a minute.                                  |

Open a key to see its details, including the permissions it holds.

The key value itself is never shown again after creation.

### Rotating an API Key

Rotate a key to replace its value, for example on a schedule or when a value may have leaked. The key keeps its name, permissions and expiration.

1. On the API keys tab, open the key's menu and select **Rotate**, or click **Rotate key** on the key's page.
2. Confirm. The previous value stops working.
3. Copy the new value and update your integration.

Only active keys, including ones that are expiring soon, can be rotated.

### Deactivating an API Key

Deactivate a key to block it while keeping its record for reference. Any service using the key stops working. A deactivated key cannot be reactivated.

1. Open the key's menu and select **Deactivate**.
2. Confirm.

### Deleting an API Key

Delete a key you no longer need. Any service using the key stops working.

1. Open the key's menu and select **Delete**, or click **Delete key** on the key's page.
2. Confirm.

{% hint style="info" %}
After a key is rotated, deactivated or deleted, allow a few minutes for the change to reach every Harmony endpoint.
{% endhint %}

### Best Practices

* **Use one key per integration.** You can then rotate or remove one integration's access without touching the others.
* **Grant the least the integration needs.** Build a small custom permission set rather than reusing an admin set.
* **Set an expiration.** Use **Never** only when the integration cannot be updated regularly.
* **Rotate keys periodically** and whenever someone who had the value leaves.
* **Never commit keys to source control.** Keep them in a secrets manager or environment variables.
* **Watch Last used.** A key that has not been used for a long time is a candidate for deletion.

### Troubleshooting

| Symptom                                          | Likely cause                                                                                     | What to do                                                                             |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| Requests return `401`                            | The `Authorization` header is missing or uses the wrong scheme                                   | Send `AccessKey <key>` to `api.harmony.io` and `Bearer <key>` to `external.harmony.io` |
| Requests return `403`                            | The key's permission sets do not grant the action, or the key is expired, deactivated or deleted | Check the key's status, then its permission sets                                       |
| A webhook call is rejected                       | The key's permission sets do not have **Trigger agents**                                         | Turn on **Trigger agents** under Agents in one of the key's permission sets            |
| A key stopped working without anyone changing it | It expired, or the person who created it was offboarded                                          | Create a new key and update the integration                                            |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.harmony.io/settings/managing-api-access-keys.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
