Authentication

How authentication works for the client API and dashboard API key management.

Client API (X-API-Key)

Every /api/v1/client/* request must include:

X-API-Key: sk_your_api_key_here

Keys are SHA-256 hashed at rest. Only the sk_ prefix is stored for identification when revoking.

curl -X GET https://cloud.storra.host/api/v1/client/users/me \
  -H "X-API-Key: sk_your_api_key_here"

Cloud Pro Requirement

Valid API keys tied to non-Pro accounts return:

{
  "detail": "API access requires Cloud Pro plan. Upgrade to use the API."
}

Status 403. Upgrade at /dashboard/settings before using the API.

Dashboard UI

1. Log in at /dashboard/login
2. Open Settings → API Keys
3. Create, view prefixes, or revoke keys

Dashboard API (Session Cookie)

Routes under /api/v1/dashboard/users/me/api-keys use the same session cookies as the web dashboard. They do not accept Authorization: Bearer headers.

Create key (requires Cloud Pro):

# Run while authenticated in the browser, or pass session cookies:
curl -X POST https://cloud.storra.host/api/v1/dashboard/users/me/api-keys \
  -H "Content-Type: application/json" \
  -b "your_session_cookies_here" \
  -d '{"label": "Production API Key"}'

Response (200):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "prefix": "sk_abc12345",
  "label": "Production API Key",
  "key": "sk_abc12345...full_key_shown_once",
  "created_at": "2025-06-01T10:30:00.000Z",
  "last_used": null
}

List keys: GET https://cloud.storra.host/api/v1/dashboard/users/me/api-keys

Revoke key: DELETE https://cloud.storra.host/api/v1/dashboard/users/me/api-keys/{prefix} - prefix is the first 11 characters (e.g. sk_abc12345). Returns {"revoked": true}.

Dashboard errors use {"error": "message"}, not detail.

Security

• Store keys in environment variables - never commit them
• Revoke compromised keys immediately via dashboard or DELETE endpoint
• Rotate keys periodically

# .env
CLOUD_API_KEY=sk_your_api_key_here

Error Responses

Missing API key (401):

{
  "detail": [
    {
      "type": "missing",
      "loc": ["header", "X-API-Key"],
      "msg": "Field required",
      "input": null
    }
  ]
}

Invalid or revoked key (401):

{ "detail": "User not found." }