feat: Update documentation surrounding CI and API keys

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="<your-api-key>"
+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.

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

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?