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:

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

Sign up at studio.stagingspaces.app
Go to Settings → API
Click Generate API Key
Save the key — it’s only displayed once

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

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.

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

{
  "error": "Authentication required",
  "message": "Provide an API key via Authorization: Bearer <key>"
}

402 — Payment Required

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

Getting Started

Core Concepts

Authentication

Authentication

API Key Authentication

Key format

Getting a key

Key security

Firebase Authentication

Endpoint Auth Summary

Error responses

401 — Unauthorized

402 — Payment Required

​Authentication

​API Key Authentication

​Key format

​Getting a key

​Key security

​Firebase Authentication

​Endpoint Auth Summary

​Error responses

​401 — Unauthorized

​402 — Payment Required

Authentication

API Key Authentication

Key format

Getting a key

Key security

Firebase Authentication

Endpoint Auth Summary

Error responses

401 — Unauthorized

402 — Payment Required