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

# API Authorization

HTTP requests to the Bird API are authorized using access keys. Access keys are scoped with permissions that control which API endpoints they can access.

Bird supports two types of access keys:

* **Organization API keys** manage organization-level resources such as users, workspaces, and billing. These can be created at [Organization > Security > API Keys](https://app.bird.com/settings/organization/access-keys).
* **Workspace access keys** manage workspace-level resources such as channels, contacts, and messaging. These can be created at **Workspace > Team > Access keys**.

Always assign only the minimum required permissions to your access keys.

## Creating an organization API key

<figure><img src="/files/iWSZXv5Z3B2np68wt4rv" alt=""><figcaption><p>Organization API Keys page</p></figcaption></figure>

1. Navigate to **Organization > Security > API Keys** and click **Create new**.
2. Give the key a meaningful **name** and **description**.
3. Select the required **permissions** from the General category (e.g. Organization Configuration Management, User Management).
4. Click **Save**.

<figure><img src="/files/HQeW7xC05aRgdZJOT9rW" alt=""><figcaption><p>Create an organization API key</p></figcaption></figure>

The access key is displayed once after creation. Copy and store it securely, as it cannot be retrieved again.

## Creating a workspace access key

<figure><img src="/files/1ndSiaNqMQH9r4gLFnt7" alt=""><figcaption><p>Workspace access keys page</p></figcaption></figure>

1. Navigate to **Workspace > Team > Access keys** and click **Create new**.
2. Give the key a meaningful **name** and **description**.
3. Select the required **permissions** from the available categories:
   * **General** -- workspace administration, IAM, SCIM, and analytics permissions
   * **Developer** -- API access for channels, contacts, conversations, numbers, templates, voice, webhooks, and more
   * **Marketing** -- campaigns, flows, journeys, and segments
   * **Email** -- sending, domains, inbound, SMTP, suppression lists, and webhooks
4. Click **Create**.

<figure><img src="/files/MwuCctIDkyEcQiVwhyRz" alt=""><figcaption><p>Create a workspace access key</p></figcaption></figure>

The access key is displayed once after creation. Copy and store it securely, as it cannot be retrieved again.

## Authorize HTTP requests with access keys

To authenticate HTTP requests with an access key, provide it in the [Authorization HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) using the following format. Replace \<access-key> with your valid access key.

```
Authorization: AccessKey <access-key>
```

## Migrating from legacy access keys

Legacy access keys that were created through the previous role-based authorization model continue to work. However, we recommend migrating to the new permission-based model for improved security and flexibility.

Legacy access keys can be viewed at <https://app.bird.com/settings/security/access-keys>. To migrate, create a new access key with the equivalent permissions and update your integration to use the new key.