> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stagingspaces.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate with the StagingSpaces API

# Authentication

The StagingSpaces API uses two authentication methods depending on the endpoint.

## API Key Authentication

**Used for:** Staging, enhancement, credits, and all programmatic access.

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

```bash theme={null}
curl https://stagingspaces-production-6fb7.up.railway.app/api/v1/credits \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"
```

### Key format

| Environment | Format        | Example                    |
| ----------- | ------------- | -------------------------- |
| Production  | `sk_live_...` | `sk_live_a1b2c3d4e5f6g7h8` |
| Test        | `sk_test_...` | `sk_test_x9y8z7w6v5u4t3s2` |

### Getting a key

1. Sign up at [studio.stagingspaces.app](https://studio.stagingspaces.app)
2. Go to **Settings → API**
3. Click **Generate API Key**
4. Save the key — it's only displayed once

<Warning>
  Keep your API key secret. Anyone with your key can use your credits.
  If a key is compromised, revoke it immediately from your dashboard.
</Warning>

### Key security

* Keys are stored as SHA-256 hashes (we never store the plaintext)
* Each key tracks `last_used_at` for audit
* Revoked keys are immediately invalid
* Test keys (`sk_test_`) work identically but are labeled for development

## Firebase Authentication

**Used for:** Dashboard operations — key management, claims, usage stats, settings.

These endpoints are designed for browser-based access from the StagingSpaces dashboard.
If you're building a server-to-server integration, you only need API key auth.

```bash theme={null}
curl https://stagingspaces-production-6fb7.up.railway.app/api/v1/keys \
  -H "Authorization: Bearer <firebase-id-token>"
```

## Endpoint Auth Summary

| Endpoint                            | Auth Method |
| ----------------------------------- | ----------- |
| `POST /api/v1/stage`                | API Key     |
| `POST /api/v1/enhance`              | API Key     |
| `POST /api/v1/place-products`       | API Key     |
| `GET /api/v1/credits`               | API Key     |
| `POST /api/v1/keys`                 | Firebase    |
| `GET /api/v1/keys`                  | Firebase    |
| `DELETE /api/v1/keys/{id}`          | Firebase    |
| `POST /api/v1/claim`                | Firebase    |
| `GET /api/v1/usage`                 | Firebase    |
| `GET/PUT /api/v1/settings/*`        | Firebase    |
| `GET/PUT /api/v1/keys/{id}/webhook` | Firebase    |
| `GET /api/health`                   | None        |

## Error responses

### 401 — Unauthorized

```json theme={null}
{
  "error": "Authentication required",
  "message": "Provide an API key via Authorization: Bearer <key>"
}
```

### 402 — Payment Required

```json theme={null}
{
  "error": "No credits remaining",
  "message": "Add credits or a payment method at studio.stagingspaces.app/api-settings",
  "credits_remaining": 0
}
```