Authentication

All API requests require a Bearer token in the Authorization header. This page covers how to create, use, and manage your API keys.

How Authentication Works

Include your API key in every request:

Authorization: Bearer sk-your-api-key

Keys use the sk- prefix. The same key works for all endpoints.

Generating an API Key

Method A — Dashboard (recommended)

1. Log in at schatziai.ch.
2. Navigate to API Keys in your account settings.
3. Click Create New Key and give it a descriptive name (e.g., "Production backend", "Local dev").
4. Copy the key immediately.

warning

Your API key is shown only once at creation. It cannot be retrieved later. Store it securely before closing the dialog.

Method B — API

Create a key programmatically with an authenticated session:

curl -X POST https://backend.schatziai.ch/api/v1/accounts/user/api-keys/create/ \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Key"}'

The response includes the full key in the key field — store it securely.

Key Limits

You can have a maximum of 5 API keys per account. If you reach the limit, revoke unused keys before creating new ones.

Managing Keys

Action	Endpoint	Method
List all keys	/api/v1/accounts/user/api-keys/	GET
View key details	/api/v1/accounts/user/api-keys/{key_id}/	GET
Rename a key	/api/v1/accounts/user/api-keys/{key_id}/update/	PATCH
Revoke a key	/api/v1/accounts/user/api-keys/{key_id}/revoke/	POST

Listed keys show a masked version (sk-***...) — the full key is never returned after creation. Each key includes usage stats: total requests, cost in CHF, and last 30 days activity.

Security Best Practices

• Never commit API keys to version control — use environment variables.
• Use separate keys for development and production.
• Revoke keys immediately if compromised.
• Give keys descriptive names so you can identify and rotate them.
• Review key usage regularly in your dashboard.

Error Responses

Authentication-related errors you may encounter:

HTTP Status	Type	Meaning
403	Forbidden	Invalid or revoked API key
402	subscription_required	No active subscription on the account

Example error body:

{
  "error": {
    "message": "Active subscription required to access this service",
    "type": "subscription_required"
  }
}

tip

If you receive a 402 error, check your subscription status in the dashboard. See Subscription & Billing for details.