Authentication

All Musha API requests require an API key passed as a Bearer token.

---

Creating an API key

1. Sign in to app.mushasec.com.
2. Go to Settings → API Keys (requires Admin or Owner role).
3. Click New API key.
4. Enter a descriptive name (e.g. github-actions-prod) and select an expiry date.
5. Copy the key — it is shown only once.

API keys follow the format msk_live_.... Store them in your CI secrets manager, never in source code.

---

Using the key

Include the key in the Authorization header of every request:

curl -H "Authorization: Bearer msk_live_your_key_here" \
  https://api.mushasec.com/v1/scans

---

Key properties

Property	Description
Expiry	Required. Maximum 1 year from creation. The key is rejected after expiry.
Scope	Keys are tenant-scoped — they can access all projects within your organization.
Rotation	Create a new key first, update your CI secrets, then revoke the old key.
Rate limits	50 scans per hour per tenant. Other endpoints have no rate limit.

---

Error responses

HTTP status	Code	Meaning
401 Unauthorized	UNAUTHORIZED	Missing, invalid, or expired API key
403 Forbidden	FORBIDDEN	Key is valid but your subscription doesn't permit this action
402 Payment Required	ACCOUNT_CANCELED	Subscription canceled
429 Too Many Requests	RATE_LIMITED	50 scans/hour limit reached

All error responses include a JSON body:

{
  "error": "UNAUTHORIZED",
  "message": "API key expired or invalid"
}

---

Idempotency

Mutation endpoints that create resources accept an Idempotency-Key header (UUID v4). Submitting the same Idempotency-Key twice within 24 hours returns the original response without creating a duplicate resource.

curl -X POST "https://api.mushasec.com/v1/scans" \
  -H "Authorization: Bearer msk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  ...

---

Request correlation

Every API response includes an X-Request-ID header. Include this ID when contacting support — it lets us find the exact request in our logs immediately.

X-Request-ID: 550e8400-e29b-41d4-a716-446655440000