Skip to content
Musher Docs

API Keys

API keys are organization-scoped credentials that authenticate requests from CLIs, SDKs, and direct API calls. You create and manage them from Settings > API Keys in the Console.

What a Key Can Access

Each API key grants access to all resources within its organization — bundles, versions, publisher settings, and organization configuration. There is one key type today; keys are not scoped to individual bundles or limited to read-only access.

Creating a Key

Open API Keys

In the Console, go to Settings > API Keys and click Create Key.

Name your key

Give the key a descriptive name that identifies its purpose, such as ci-production or local-dev.

Copy the token

The full token is displayed once. Copy it and store it in a secret manager or environment variable before closing the dialog.

Using a Key

bash 
musher auth login

Paste the key when prompted. The CLI stores it securely in your OS keyring — it never appears in shell history.

For full setup instructions covering CLIs, SDKs, and CI/CD pipelines, see Authentication.

Rotating a Key

Rotate keys by creating a replacement before revoking the old one. Both keys work simultaneously until you revoke, so there is no downtime.

Create a new key

Follow the creation steps above to generate a replacement key.

Update your consumers

Replace the old key value in your environment variables, CI/CD secrets, and any other systems that use it.

Verify the new key

Confirm the new key works before proceeding:

bash 
curl -H "Authorization: Bearer $MUSHER_API_KEY" \
  https://api.musher.dev/agent/v1/runner/me

Revoke the old key

Once the new key is confirmed working everywhere, revoke the old key from the Console.

Revoking a Key

To revoke a key, find it in the Settings > API Keys list and click Revoke. You will be asked to confirm.

If a Key Is Leaked

  1. Revoke the compromised key immediately from Settings > API Keys in the Console.
  2. Create a replacement key and update all consumers.
  3. Review recent activity to check for unauthorized access. If your organization has audit logging enabled, check for unexpected API calls during the exposure window.

Security Best Practices

  • Use one key per environment (development, staging, production)
  • Rotate keys periodically, even if they have not been compromised
  • Never commit keys to version control
  • Use your CI/CD platform's secret management instead of plain-text config files
  • Never log or print API keys in CI output
  • Revoke unused keys promptly

Current Limitations

API keys are scoped to the entire organization. There are no per-bundle scopes, read-only keys, or fine-grained permissions today. To limit the impact of a compromised key, use separate keys for each environment and revoke keys you no longer need.