Sign inGet Started

Bird for Stripe Projects

Bird for Stripe Projects connects a Bird workspace to a Stripe project and provisions a Bird API key into that project's environment. Your app or coding agent reads the key from .env like any other project credential, so nobody copies it from the Bird dashboard. Provisioning is free. Bird bills your usage at the rates on the pricing page.

Before you start

  • A Stripe account and the Stripe CLI with the Projects plugin (stripe plugin install projects).
  • A Bird account with the Owner, Admin, or Developer role in the workspace you want to connect. These roles can manage API keys, which linking needs. You can also create the account during authorization.

Install the app

Stripe Projects installs the Bird app the first time you run stripe projects link or stripe projects add for Bird. Start with Add Bird to your project to connect your workspace and create a key.

Add Bird to your project

  1. In your app's directory, create a project if it doesn't have one yet:

    Codebeispiel
    stripe projects init
  2. Add Bird API access, and name the resource so you can manage the key later:

    Codebeispiel
    stripe projects add bird/bird-api-access --name bird-key

    The first time, Stripe asks you to accept Bird's terms of service and privacy policy, then opens Bird in your browser so you can authorize the connection.

    When you approve, the command finishes and reports 2 credentials created for Bird: BIRD_API_KEY and BIRD_API_BASE_URL. Stripe writes them to your project's .env file.

    To connect Bird without provisioning a key yet, run stripe projects link bird instead.

  3. To load the same credentials on another machine or in a fresh clone of the project, run:

    Codebeispiel
    stripe projects env --pull

If your project still uses BIRD_BIRD_API_KEY and BIRD_BIRD_API_BASE_URL, update your app and environment to use BIRD_API_KEY and BIRD_API_BASE_URL. Keep the current working values when renaming.

What happens when you authorize

The first time you link Bird, Stripe opens Bird in your browser:

  1. Sign in to Bird, or create an account. Bird asks for your usual multi-factor authentication if it's turned on.
  2. Choose the workspace to connect. A Stripe account stays connected to the workspace you choose here; you can't move it to another workspace later.
  3. Review the permissions and select Allow for Stripe Projects. Keep API keys at read and write access so Stripe Projects can manage the key. Also keep at least one permission the issued key can use, such as sending email. API keys itself cannot go on the issued key.

Bird then returns you to Stripe, which finishes linking. When the project adds Bird API access, Bird creates an API key for the project in the connected workspace, and Stripe stores it in the project's vault:

  • BIRD_API_KEY is the key. It gets the permissions you approved that an API key can hold. Workspace write access isn't one of them.
  • BIRD_API_BASE_URL is the API host for your workspace's region, such as https://us1.platform.bird.com or https://eu1.platform.bird.com.

Send the key as a bearer token to BIRD_API_BASE_URL, as described in Authentication.

Manage the key

Run these commands from your project's directory.

Rotate the key

Use the bird-key resource name from Add Bird to your project:

Codebeispiel
stripe projects rotate bird-key

Rotating writes the new key to your .env file and revokes the old key at once. Anywhere else that uses the key, such as another machine or a deployed app, still holds the old key until you run stripe projects env --pull there or update its environment. Reload the credential or restart the app after updating it.

Open the workspace

Codebeispiel
stripe projects open bird

This opens the Bird dashboard for the connected workspace and asks you to sign in if you aren't already.

Disconnecting Stripe Projects ends its management access. Issued keys remain active in the connected workspace.

Use a separate workspace for testing

Bird API keys have no separate test mode. A key added from a Stripe sandbox is a live key in the connected workspace: it shares that workspace's data, senders, and usage billing. For testing, link a separate Stripe account or sandbox to a separate Bird workspace. Check the connected workspace before you add a key.

Troubleshooting

  • A deployment returns 401 after a rotation. Check whether that copy still holds the old key. Run stripe projects env --pull where it runs, or update the deployed environment, then reload the credential or restart the app. If the latest value still fails, check the key's status in the connected workspace. Pulling doesn't restore a revoked key; see creating a key for a replacement.
  • stripe projects init says your account isn't eligible. Open the link the error gives and finish setting up Stripe Projects for that Stripe account in your browser, then run the command again.
  • stripe projects add can't find Bird. Run stripe projects search bird, which lists Bird API access as bird/bird-api-access.

For help, contact Bird support.

Next steps