API Authentication

Authenticate your API requests using API keys and Bearer tokens.

See the Authentication guide for setup instructions, CLI configuration, and verifying your key.

Bearer Token

Include your API key as a Bearer token in the Authorization header:

http

Authorization: Bearer mush_your_api_key_here

API keys are scoped to your organization. Create and manage them from Settings > API Keys in the Musher Console, or via the Organizations API.

Scopes

Every API key has one or more permission scopes that control what operations it can perform. Scopes follow a hierarchy — higher scopes include all permissions of lower scopes.

Scope	Includes	Operations
`read`	—	List and read bundles, versions, assets, queues
`write`	`read`	Create, update, delete, publish, push, yank bundles and assets; manage queues
`admin`	`write` + `read`	All operations (reserved for future administrative actions)

Default scope

When you create an API key without specifying scopes, it defaults to read only. This follows the principle of least privilege.

Creating a key with write scope

bash

curl -X POST https://api.musher.dev/v1/organizations/{org_id}/api-keys \
  -H "Authorization: Bearer $MUSHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI Publisher", "scopes": ["read", "write"]}'

Scope errors

When an API key lacks the required scope for an operation, the API returns a 403 Forbidden response in RFC 9457 Problem Details format:

json

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "API key requires 'write' scope"
}

To resolve this, create a new API key with the required scope. Existing keys cannot have their scopes changed after creation.