Organization master keys

Available on request: Contact your Bird representative to enable organization master keys for your organization.

Use a master key when your application needs to manage several workspaces in one organization. A master key can create, rename, and delete workspaces and make HTTP API requests with workspace administrator permissions in those workspaces. Workspace requests specify their target workspace; organization requests use the organization bound to the key.

You must be an organization owner or administrator with access to at least two workspaces in that organization to manage master keys. Access to an individual workspace does not grant access to master key management.

For an integration that needs one workspace with a narrower permission set, use a workspace API key.

Create a master key

Creating a master key requires an available slot in your organization’s allowance. Revoking a key frees its slot. Rotation replaces a key without using another slot, including while the old credential remains valid during its grace period. Contact your Bird representative if you need a higher limit.

1. Open the Dashboard and select your organization.
2. Open Master keys in the organization sidebar, then select Create master key.
3. Enter a name that identifies the application or environment, such as Production integration.
4. Select Create master key and save the returned key in your secret manager.
5. Select I've saved my key to close the dialog.

The full key appears once. You cannot retrieve it from the list later. If you lose it, rotate the key to obtain a replacement.

Master keys start with bm_ (Bird master), followed by the region, for example bm_eu1_.

New master keys have no expiry. Their access is fixed; you do not select individual scopes when creating one. The key applies to current and future workspaces in its organization. Removing the person who created it does not revoke the key.

Make an organization request

Send the master key as a bearer token. The key identifies your organization. Use the regional API host that matches the key: https://eu1.platform.bird.com for eu1, or https://us1.platform.bird.com for us1.

Set BIRD_API_URL to that host and load BIRD_MASTER_KEY from your secret manager.

Organization operations use the organization bound to the key. You do not need to send X-Organization-Id. Workspace provisioning remains subject to the organization’s workspace quota.

Make a workspace request

Set BIRD_WORKSPACE_ID to a workspace ID from the organization. Send it in X-Workspace-Id on workspace requests:

curl "$BIRD_API_URL/v1/workspace" \
  -H "Authorization: Bearer $BIRD_MASTER_KEY" \
  -H "X-Workspace-Id: $BIRD_WORKSPACE_ID"

A successful response returns 200 with the selected workspace. Product requests, such as reading email messages, use the same workspace header. You do not need X-Organization-Id: the key already identifies its organization.

If you send both context headers, they must identify a workspace and its owning organization. A master key cannot reach another organization's workspaces. Selecting a workspace does not combine its credentials, configuration, or resources with another workspace.

Master keys support HTTP requests, with an explicit workspace header for workspace operations. Master keys do not authenticate SMTP or SIP connections. Use workspace credentials for those connections and for CLI or MCP commands that do not accept an explicit master-key target.

Understand the access limits

A master key can create, rename, and delete workspaces. Within each workspace, it has the full workspace administrator role, including product configuration, automations, API keys, and connected integrations. It cannot delete the organization's last remaining workspace. It can also issue workspace API keys, invite people to a workspace, and manage workspace membership.

A master key cannot manage other master keys, organization roles, organization-role invitations, billing funding, payment methods, SSO, or security policies. Master keys do not grant unrestricted access to organization APIs. Product availability, workspace limits, and each operation's access requirements still apply.

Rotate a master key

1. On Master keys, open the key's actions menu and select Rotate.
2. Choose when the old key should stop: Immediately, After 24 hours, or After 7 days. The default is After 24 hours.
3. Select Rotate master key and save the replacement in your secret manager.
4. Update your application to use the replacement before the old key's grace period ends.

The replacement keeps the name and access of the old key and has no expiry. Its full value appears once. If the old key already expires sooner than the selected grace period, the earlier expiry still applies.

A key can be rotated once. For another rotation, select its replacement. If a key is exposed, choose Immediately or revoke it.

Revoke a master key

On Master keys, open the key's actions menu, select Revoke, and confirm Revoke master key. Applications using it lose access. Revocation is permanent; the record remains available under Show revoked keys.

If your allowance returns to zero, you can still rotate or revoke existing keys. After you revoke the last key, the sidebar entry disappears and you return to organization Home. Creating a new key requires an allowance increase.

Revocation usually takes effect almost immediately, though a short delay is possible. If you are replacing a key during routine maintenance, update your application before revoking its old credential.

Troubleshoot requests

Next steps

• Workspace API keys: create credentials with a narrower permission set.
• Base URLs and regions: choose the API host for your requests.
• Idempotent requests: retry supported mutations without repeating their effect.