# Authentication

> API version: v1

Every endpoint except [Status](https://studyingstocks.com/developers/status) needs an API key, sent in the `X-Api-Key` header:

```bash
curl "https://studyingstocks.com/api/v1/companies/AAPL" -H "X-Api-Key: ss_live_..."
```

## The key

- A key looks like `ss_live_` followed by 40 random letters and digits.
- **Header only.** There is no `?apikey=` query parameter, on purpose: keys in URLs end up in server logs, proxies and browser history. A key in the query string is ignored and the request is answered with `401`.
- Keep the key secret and do not use it in code that runs in a browser or an app you distribute.

## Creating, regenerating and revoking

Only active Premium subscribers can manage a key, on the [profile page](https://studyingstocks.com/profile#api-access):

- **Create:** the full key is shown **once**. We store only a SHA-256 hash and the first characters (the prefix), so we cannot show it again or recover it.
- **Regenerate:** creates a new key and revokes the old one at once. Do this if a key may have leaked.
- **Revoke:** the key stops working at once.

## When the subscription ends

A key works only while its owner's Premium subscription is active. When the subscription lapses, requests are answered with `403` and the code `subscription_inactive`. Because the check is cached, this can take up to 5 minutes to show. Renew the subscription and the same key works again.

## Errors

| Status | Code | Meaning |
|---|---|---|
| 401 | `unauthenticated` | The header is missing, or the key is malformed, unknown or revoked |
| 403 | `subscription_inactive` | The key is valid but its Premium subscription is not active |
| 429 | `rate_limited` | Too many requests (also for repeated requests with a wrong key from one IP address) |

See [errors](https://studyingstocks.com/developers/errors) for the format.