# Authentication for LightMySky

> Most of this API needs no authentication. Read the first section before you build a login.

## No key needed

The catalog is open. These routes answer any client, with no key, no sign-up and no
origin restriction:

- `GET /api/v1/topics`
- `GET /api/v1/topics/{id}`
- `GET /api/v1/topics/{id}/content`
- `GET /api/v1/topics/{id}/prerequisites`
- `GET /api/v1/topics/{id}/unlocks`
- `GET /api/v1/subjects`
- `GET /api/v1/standards/{key}/topics`
- `GET /api/v1/packs/format`

Every public page also answers in Markdown, either through `Accept: text/markdown`, a
`.md` address, or `?mode=agent`. None of that needs a key either.

## When a key is needed

A key is needed only for the routes that belong to one account: a learner's mastery,
their next question, their reports, and the packs an account owns. Those routes carry
personal progress, so they are never open.

## Scheme

HTTP Bearer, on every request:

```
Authorization: Bearer atlas_sk_...
```

- Type: `http`, scheme `bearer` (see `components.securitySchemes.bearerAuth` in
  https://lightmysky.com/openapi.json).
- A missing or unknown key is answered `401` with
  `{ "error": "Missing Authorization: Bearer <api key>", "code": "unauthorized", "status": 401 }`.
- A key that belongs to another account is answered `404`, not `403`: one account cannot
  learn whether another account's learner exists.
- There is no OAuth flow, no refresh token and no token endpoint. A key is a long-lived
  secret issued to an account.

## Getting a key

1. Create a free account at https://lightmysky.com/signup.
2. Follow the quickstart at https://lightmysky.com/dev, which shows where the key is issued and how
   to call the first learner route with it.
3. Keep it server-side. A key in a browser is a key in everybody's hands.

If you are building something and the limits do not fit, write to info@lightmysky.com and
say what you are building.

## Endpoints

- Base URL: https://lightmysky.com/api/v1
- Machine-readable description: https://lightmysky.com/openapi.json
- Service catalog (RFC 9727): https://lightmysky.com/.well-known/api-catalog
- Human documentation: https://lightmysky.com/dev
- When to use this site at all: https://lightmysky.com/agent-instructions.md

## Limits and lifecycle

- 600 requests a minute, counted against the key when there is one and the caller IP
  otherwise. Every answer carries `RateLimit-Limit`, `RateLimit-Remaining` and
  `RateLimit-Reset`; over the ceiling the answer is `429` with `Retry-After`.
- A write can carry `Idempotency-Key`. Repeating the same key on the same path within 24
  hours returns the first answer again, marked `Idempotency-Replayed: true`.
- Cache what you fetch, and name your agent in `User-Agent`.
- The major version sits in the path. A version that is going away will carry
  `Deprecation` and `Sunset` headers (RFC 8594) for at least six months first. Nothing is
  deprecated today.