diff --git a/src/content/docs/account/api-keys.mdx b/src/content/docs/account/api-keys.mdx new file mode 100644 index 00000000..b510955d --- /dev/null +++ b/src/content/docs/account/api-keys.mdx @@ -0,0 +1,89 @@ +--- +title: API Keys +description: Create and manage API keys for CI and programmatic access +sidebar: + order: 3 +--- + +API keys let you authenticate with Shorebird from CI systems and other automated +environments. You can create, view, and revoke API keys from the +[Shorebird Console](https://console.shorebird.dev). + +## Creating an API Key + +1. Open **Account → API Keys** in the console. +2. Click **Create API Key**. +3. Enter a descriptive name (e.g., "GitHub Actions — my-app"). +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 in your CI platform. +Shorebird CLI commands will authenticate automatically when this variable is +present. + +```sh +export SHOREBIRD_TOKEN="" +shorebird patch android +``` + +For platform-specific setup, see our CI guides for +[GitHub Actions](/code-push/ci/github/), [Codemagic](/code-push/ci/codemagic/), +or the [generic CI guide](/code-push/ci/generic/). + +## Expiration + +API keys default to a one-year expiration. During creation you can choose from: + +- 30 days +- 90 days +- 1 year (default) +- No expiration + +All expiration options are available on every plan. + +## Permissions + +API keys support two permission levels: + +- **Full access** — the key has the same permissions as your account. Available + on all plans. +- **Release & Patch only** — the key can create releases and patches, but cannot + manage apps, organizations, members, or billing. Available on Pro and Business + plans. + +## Revoking an API Key + +To revoke a key, find it in the API Keys list and click **Delete**. Revocation +is immediate — 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 is deprecated. Existing tokens generated by +`login:ci` will continue to work until September 2026, but we recommend +replacing them with API keys created from the console. + +To migrate: + +1. Create a new API key in the console. +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. + +## Security + +- API keys use the `sb_api_` prefix. This prefix is registered with + [GitHub secret scanning](https://docs.github.com/en/code-security/secret-scanning/introduction/about-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. diff --git a/src/content/docs/code-push/ci/_authentication.mdx b/src/content/docs/code-push/ci/_authentication.mdx index adc253bf..7fb9e669 100644 --- a/src/content/docs/code-push/ci/_authentication.mdx +++ b/src/content/docs/code-push/ci/_authentication.mdx @@ -1,44 +1,31 @@ -Most Shorebird functionality, like creating releases and patches, requires being -authenticated. In order to authenticate with Shorebird in CI, you will need to -generate a CI token. +Most Shorebird functionality, like creating releases and patches, requires +authentication. To authenticate in your CI, create an API key from the +[Shorebird Console](https://console.shorebird.dev): -```sh -shorebird login:ci -``` +1. Go to **Account → API Keys**. +2. Click **Create API Key**. +3. Give the key a name (e.g., "GitHub Actions — my-app"), choose an expiration, + and select a permission level. +4. Copy the key value — it is only shown once. -You will be prompted to go through a similar OAuth Flow as when using -`shorebird login`, however, `shorebird login:ci` will not store any credentials -on your device. Instead, it will output a base-64 encoded auth token that you -will use in your CI environment. +Use this key as your `SHOREBIRD_TOKEN` in CI. The environment variable name is +unchanged from previous versions. -The output of this command should look something like: - -{/* cSpell:disable */} - -``` -$ shorebird login:ci -The Shorebird CLI needs your authorization to manage apps, releases, and patches on your behalf. - -In a browser, visit this URL to log in: - -https://auth.shorebird.dev/login... - -Waiting for your authorization... - -🎉 Success! Use the following token to login on a CI server: - -qwerasdf1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqw== +:::caution -Example: +`SHOREBIRD_TOKEN` is a secret. Do not check it into source control or share it +publicly. Store it in your CI platform's secrets manager. -export SHOREBIRD_TOKEN="$SHOREBIRD_TOKEN" && shorebird patch android -``` +::: -{/* cSpell:enable */} +See [API Keys](/account/api-keys/#permissions) for details on permission levels +and other key management options. -:::caution +:::tip[Migrating from `shorebird login:ci`] -The `SHOREBIRD_TOKEN` is a secret and should not be checked in to your source -control or shared publicly. +The `shorebird login:ci` command is deprecated. Existing tokens generated by +`login:ci` will continue to work until September 2026, but new tokens should be +created from the console. The `SHOREBIRD_TOKEN` environment variable name has +not changed, so your CI workflow files need only a new key value. ::: diff --git a/src/content/docs/code-push/faq.mdx b/src/content/docs/code-push/faq.mdx index 85824ddf..d54804e0 100644 --- a/src/content/docs/code-push/faq.mdx +++ b/src/content/docs/code-push/faq.mdx @@ -69,9 +69,10 @@ for distribution. ### Can I use Shorebird from my CI system? -Yes. Shorebird is intended to be used from CI systems. We've published a -[generic guide for CI setup](/code-push/ci/generic/) as well as other CI -systems. +Yes. Create an API key in the [Shorebird Console](https://console.shorebird.dev) +under **Account → API Keys**, then add it to your CI environment as +`SHOREBIRD_TOKEN`. See our [CI setup guide](/code-push/ci/generic/) for detailed +instructions. ### Can I use Dart defines with Shorebird?