DokumentacjaEngagement Platform API
Sign inGet started
Guides
API

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.
  • 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

Organization API Keys page
  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.
Create an organization API key
The access key is displayed once after creation. Copy and store it securely, as it cannot be retrieved again.

Creating a workspace access key

Workspace access keys page
  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.
Create a workspace access key
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 using the following format. Replace <access-key> with your valid access key.
Przykład kodu
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.