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

# Authentication

> Bearer tokens, sandbox vs live keys, key rotation

All API requests (except the unauthenticated health check at `GET /api/health`) require a Bearer token in the `Authorization` header.

```
Authorization: Bearer sk_live_...
```

## Getting an API key

API keys are provisioned by the MyUstadia team. They are not self-service. There is no signup page.

To request access, email [sales@myustadia.com](mailto:sales@myustadia.com) with:

* Your company name and the use case you plan to integrate
* Whether you want a sandbox (test) key only, or sandbox plus a live production key
* A technical contact email for ongoing communication

Once approved, you will receive both keys out of band. The same channel is used to bump quota, rotate keys, or close an account.

## Key types

Your account has exactly one live key and one test key. Both are issued at provisioning time and are Stripe-style opaque tokens.

| Prefix     | Environment | Billing                 | What it does                                                   |
| ---------- | ----------- | ----------------------- | -------------------------------------------------------------- |
| `sk_test_` | Sandbox     | Free, no quota consumed | Returns the canonical demo course; useful for integration work |
| `sk_live_` | Production  | Consumes quota          | Runs the real generation pipeline                              |

<Warning>
  Treat `sk_live_` like a password. It can spend quota and surface paid generations. Never commit it to git. Never paste it into client-side JavaScript.
</Warning>

## Live keys

`sk_live_` keys hit the real pipeline. Each course generation consumes seconds from your account's monthly quota.

When the live cost meter crosses your billing cap mid-generation, the affected course status becomes `paused_quota_exceeded`. You can resume by purchasing additional quota or wait for the next billing cycle to reset.

## Sandbox keys

`sk_test_` keys run in sandbox mode, a fetch model:

* Course creation succeeds and returns a real `course_id`, but generation is **skipped**.
* Status polling returns `ready` immediately.
* Delivery endpoints (video, slides, notes, quiz) serve content from one shared, pre-built demo course (`20260621_001352_0fca91`).
* `sk_live_` keys never see the sandbox course; the two are fully isolated.
* Webhook deliveries still fire with sandbox payloads if a webhook URL is configured.

Use your sandbox key for all integration work until your code is solid, then swap to the live key.

## Key rotation

To rotate a key, email [sales@myustadia.com](mailto:sales@myustadia.com). The team issues a new key, invalidates the old one, and sends the replacement out of band. Self-serve rotation is on the roadmap.

## Errors

A missing or invalid key returns `401`:

```json theme={null}
{
  "detail": {
    "error": {
      "type": "authentication_error",
      "message": "Missing or invalid API key"
    }
  }
}
```

A correctly-shaped key that belongs to a different account when you request a course will return `404 not_found_error / course_not_found`, never a permissions error. This is to avoid leaking the existence of resources you do not own.