API Keys

API keys let you authenticate with Shorebird from scripts and other automated environments. You can create, view, and revoke API keys from the Shorebird Console. From the command line, shorebird tokens list lists your keys when you’re signed in with shorebird login (with an API key or GitHub Actions OIDC, it opens the console page instead), and shorebird tokens create and shorebird tokens delete open the console page (Shorebird 1.6.135 or newer).

The keys on this page are personal: each one acts as you, with at most your role, and stops working if your account is deleted. For CI and integrations your team depends on, use a service account instead. Its keys belong to the organization and do what the service account’s role allows.

Creating an API key

Watch the video: Create a Shorebird API key

1. Open Account → API Keys in the console.
2. Click Create API Key.
3. Enter a descriptive name (e.g., “Scripts on my laptop”).
4. Choose an expiration period.
5. Select a permission level.
6. Click Create.

The full key value is shown exactly once after creation. Copy it and store it securely. It cannot be retrieved again.

Using an API key

Set the key as the SHOREBIRD_TOKEN environment variable where your script runs. Shorebird CLI commands will authenticate automatically when this variable is present.

export SHOREBIRD_TOKEN="<your-api-key>"
shorebird patch android --release-version=latest --track=stable

For CI, use a service account’s key in SHOREBIRD_TOKEN instead. For platform-specific setup, see the CI guides for GitHub Actions, GitLab, Codemagic, or the generic CI guide.

Expiration

API keys default to a 1-year expiration. During creation, you can choose from:

• 30 days
• 90 days
• 1 year (default)

A key can’t be set to never expire.

Existing keys without an expiration keep working until you revoke them. Regenerating one gives the new key an expiration.

For a key that never expires, or one that doesn’t depend on any one person’s account, use a service account.

Permissions

API keys support two permission levels:

• Full access: the key can do everything your account can, except delete your account, change billing limits, manage your sessions and API keys, manage service accounts and their keys and trust rules, or set and remove App Store and Google Play credentials. Do those signed in to the console, or, for service accounts, with shorebird login. Available on all plans.
• Release and patch only: the key can create releases and patches, but cannot manage apps, organizations, members, or billing. Available on all plans.

A key that tries one of the things no key can do gets this error:

Personal access tokens can't delete accounts, change billing limits, manage sessions and tokens, manage service accounts, or manage App Store and Google Play credentials. Sign in to the Shorebird console to do this.

Revoking an API key

To revoke a key, find it in the API Keys list and click Delete. Revocation is immediate, and any CI pipeline using that key will fail on its next run. This action cannot be undone.

Migrating from shorebird login:ci

The shorebird login:ci command has been replaced by API keys, and tokens it generated stopped working on October 1, 2026. Replace them with a service account’s key, so CI doesn’t depend on your account.

To migrate:

1. Create a service account and create a key for it.
2. Replace the SHOREBIRD_TOKEN value in your CI secrets with the new key.
3. Verify your CI pipeline runs successfully.

The SHOREBIRD_TOKEN environment variable name has not changed, so no workflow file edits are needed beyond updating the secret value.

Logins made on your own machine with a Shorebird CLI older than 1.6.87 stopped working on October 1, 2026 as well. Run shorebird upgrade, then shorebird logout and shorebird login.

Security

• API keys use the sb_api_ prefix. This prefix is registered with GitHub secret scanning, so leaked keys in public repositories are flagged automatically.
• Keys are stored as irreversible hashes. Shorebird cannot retrieve a key value after creation.
• Treat API keys like passwords. Store them in your CI platform’s secrets manager and do not commit them to source control.