# Create an API key

_Category: Integrations and API_

Create an API key to connect your help center to your own code, scripts and tools through the HelpCenter.io API. Sync articles with other systems, power your own search, automate content updates or pull your statistics into internal dashboards.

**Who can do this:** Owners and Admins · **Plans:** All plans

## Create a key

1. In the left menu, click the gear icon, then **Settings**.
2. Under **API keys**, click **New key**.
3. In **Name**, say where the key will be used, for example "Docs sync script". A clear name tells you later which key to delete.
4. Pick a **Scope**: **Read only** or **Read & write**.
5. Leave **Team notes** off unless the integration needs your team's editorial notes, and **Design** off unless it changes how your help center looks. Leave **Custom domain** and **Redirects** off too.
6. Click **Create key**.
7. Click **Copy** next to the new key right away and store it somewhere safe, such as a password manager or your server's secret settings. The full key is shown only this once.

![Screen recording. Under API keys, click New key. Name it after where it will be used, and pick a Scope. Leave Team notes, Design, Custom domain and Redirects off unless the integration needs them. Click Create key, then Copy it somewhere safe.](https://helpcenter-io.s3.amazonaws.com/uploads/self/OV1ElxlIppDuMWj49SRObz87YYdgu2fRh9OE2nau.gif)
Copy a new key as soon as you create it.

Once you leave the page, the list shows only the last four characters of each key, with its scope, a **Team notes** tag if it has notes access and a **Design** tag if it has design access. A key that can manage your custom domain carries a **Custom domain** tag, and one that can redirect to other sites an **External redirects** tag. Under each key you see who created it, when, and when it was last used. Lost a key? Create a new one, switch your integration to it and delete the old one.

## Choose a scope

| Option | What the key can do |
| --- | --- |
| **Read only** | Read your articles, categories, comments and statistics, without changing anything. |
| **Read & write** | Everything a read-only key can do, plus create, update and delete articles and categories, upload images, moderate comments, manage webhooks and choose which websites can show your widget and embedded help center (your [embedding origins](https://self.helpcenter.io/content/embedding-origins)). |
| **Team notes** (optional) | Read the private notes your team leaves on articles. With **Read & write**, also answer and resolve them. Readers never see these notes. |
| **Design** (optional) | Read your help center's design. With **Read & write**, also change and publish the theme, pages, components, custom CSS and scripts. |
| **Custom domain** (optional) | Connect, check and remove your help center's [custom domain](https://self.helpcenter.io/content/custom-domain). Needs a **Read & write** key. A key with this access can disconnect or replace the address your readers visit, so give it only to tools that set up your domain. |
| **Redirects** (optional) | Any **Read & write** key can create [redirects](https://self.helpcenter.io/content/custom-redirects) that lead to pages of your help center. With this access, a key can also send readers on to other sites, so give it only to tools you trust. Needs a **Read & write** key. |

You choose the scope when you create a key, and you can't change it later. To move an integration from **Read only** to **Read & write**, create a new key, switch the integration to it and delete the old one. **Team notes**, **Design**, **Custom domain** and **Redirects** access you can change at any time, without replacing the key. The developer portal explains the requests behind the last two: [Custom domain](https://developers.helpcenter.io/content/custom-domain-api) and [Redirects](https://developers.helpcenter.io/content/redirects-api).

## Change a key's access

1. Under **Settings** → **API keys**, click **Edit access** next to the key.
2. Tick or untick the access the integration needs, such as **Team notes** or **Design**.
3. Click **Save access**.

The key keeps the same token, so you don't need to update your integration. The change applies from its next request.

## Give a key access to your design

Tick **Allow access to the help center design** when an integration should work on your design: the theme, pages, components, navigation, custom CSS and scripts. Design access includes custom CSS and scripts, which run on every page of your help center, so give it only to tools you trust.

1. Under **API keys**, click **New key** and name the key.
2. Pick **Read & write** if the key should change and publish your design. A **Read only** key can read the design but not change it.
3. Under **Design**, tick **Allow access to the help center design**.
4. Click **Create key**. The key appears in the list with a **Design** tag.

![Screen recording. Click New key and name the key. Pick Read & write so the key can change and publish your design. Tick Allow access to the help center design. Click Create key. The new key carries a Design tag.](https://helpcenter-io.s3.amazonaws.com/uploads/self/XUUmfoFHMPaZkyhR3hYJTixnj3ySM3qmWFJiyEhB.gif)
A key with design access carries a Design tag.

A key with design access edits the same draft you see in the template editor. You can review its changes there with the live preview, and visitors see nothing until the draft is published, either by you in the editor or by the integration with a **Read & write** key. The [Design API](https://developers.helpcenter.io/content/design-api) article on the developer portal explains each request.

## Use your key

Whoever builds the integration sends the key in the `apikey` header of each request to `https://api.helpcenter.io/v1`. A key works only with the help center it was created in. For a first request, follow [Quickstart: your first API request](https://developers.helpcenter.io/content/quickstart-your-first-request) on the developer portal. [API keys](https://developers.helpcenter.io/content/api-keys) there explains how keys work in detail.

A key can also connect an AI agent you build to your help center, on the Growth and Catalyst plans. See [Connect Claude, ChatGPT and other AI agents](https://self.helpcenter.io/content/connect-ai-agents).

## Limits and errors

Each key can make up to 300 requests a minute, with lower limits for changes and for statistics. A key that goes over a limit gets `429` responses until it may try again. [Rate limits](https://developers.helpcenter.io/content/rate-limits) on the developer portal has the numbers and how to handle them, and [Errors](https://developers.helpcenter.io/content/errors) explains every error response.

## Keep your keys safe

- Use **Read only** keys whenever you don't need to change content.
- Leave **Team notes**, **Design**, **Custom domain** and **Redirects** off for integrations that only work with articles. You can turn access on later with **Edit access**.
- Create a separate key for each integration, so you can delete one without breaking the others.
- Never put a key in code that runs in the browser or in a public repository. The widget doesn't need an API key.
- To replace a key, create a new one, switch your integration to it, then delete the old one.
- Delete keys you no longer use.

## Delete a key

1. Under **Settings** → **API keys**, click the trash icon next to the key.
2. Click **Delete key** to confirm.

Requests using that key stop working immediately.

## The key an AI agent leaves you

If an AI agent built your help center and you let it finish setting up when you claimed it, its key is listed as **AI agent (setup)**. It works for 30 days after the claim, and the list shows the date it expires. After that it carries an **Expired** tag and requests with it are refused. The first time you publish the help center, you choose whether the agent may keep editing it. To end its access sooner, delete the key. See [Claim a help center an AI agent built for you](https://self.helpcenter.io/content/claim-a-help-center-an-ai-agent-built).

An agent's key can create redirects only to pages of your help center, even with **Redirects** access.

## Who can see a key

Every Owner and Admin of your help center sees all of its keys, whoever created them, and can delete any of them.

A key works only while the person who created it is an Owner or Admin of this help center. When you remove them from the team or give them another role, their keys stop working on the next request, with nothing for you to revoke. The list then marks those keys **Not working** and says why.

**Removing an Admin or changing their role?** First switch the integrations that use their keys to a key created by an Owner or Admin who stays.

## Related articles

- [The HelpCenter.io API](https://self.helpcenter.io/content/using-the-helpcenter-io-api)
- [Connect Claude, ChatGPT and other AI agents](https://self.helpcenter.io/content/connect-ai-agents)
- [API keys](https://developers.helpcenter.io/content/api-keys) on the developer portal
- [Quickstart: your first API request](https://developers.helpcenter.io/content/quickstart-your-first-request) on the developer portal
