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

# Authentication

> How to authenticate requests to the Radion API with API keys.

You need an API key for all business requests under `/v1/*`. Keys are free. Get one at [radion.app/dashboard](https://radion.app/dashboard). You do not need a paid plan.

Send your key in the `X-API-Key` header:

```bash title="Authenticated request" theme={null}
curl "https://api.radion.app/v1/polymarket/events?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"
```

Use the key value as it is. Do not put `Bearer` in front of it.

## Key types

Radion has two kinds of keys:

* **Secret keys** (`sk_...`) — for your own server. They give full access to your plan. Keep them secret.
* **Public JWT keys** (`pk_jwt_...`) — safe to ship in a browser or mobile app. On their own they do nothing. Each request also needs a signed user token (a JWT) from your own auth provider.

## Public JWT keys

Use a public JWT key when your app has no backend and talks to Radion straight from the browser.

Set the key up once in the [dashboard](https://radion.app/dashboard):

* Give Radion a **JWKS URL** or paste a **public key** (PEM). This is how Radion checks your users' tokens.
* Optional: set an **audience** (`aud`) and **issuer** (`iss`) to check.
* Optional: set a per-user rate limit.

Then send two headers on each request: the public key, and the user's JWT.

```bash title="Public JWT request" theme={null}
curl "https://api.radion.app/v1/polymarket/events?limit=10" \
  -H "X-API-Key: pk_jwt_YOUR_PUBLIC_KEY" \
  -H "Authorization: Bearer USER_JWT"
```

Radion checks the JWT signature against your configured key, checks `exp` (and `aud`/`iss` if you set them), and reads the `sub` claim. Rate limits then apply per user (`sub`), not per key. Monthly usage still counts against your plan.

### Token rules

* The JWT must use an **asymmetric** algorithm: `RS256/384/512`, `PS256/384/512`, `ES256/384`, or `EdDSA`. Symmetric algorithms (`HS256` and friends) are rejected, because the public key is meant to be public.
* The JWT must have `exp` (expiry) and a non-empty `sub`.
* A JWKS URL must be `https` and must not point at a private or internal address.

A leaked public key is low risk. It does nothing without a valid user JWT from your provider.

## Look at the current key

`GET /auth/me` tells you about the key you are using. This call is free. It does not count against your quota.

```bash title="Inspect the current API key" theme={null}
curl "https://api.radion.app/auth/me" \
  -H "X-API-Key: YOUR_API_KEY"
```

```json title="Response" theme={null}
{
  "keyLabel": "production_read",
  "plan": "starter",
  "callCount": 42,
  "createdAt": "2026-04-01T12:00:00Z",
  "lastUsedAt": "2026-04-09T15:20:00Z",
  "monthlyUsage": {
    "used": 120,
    "limit": 3000,
    "resetsAt": "2026-07-01T00:00:00Z"
  },
  "requestsPerSecond": null
}
```

| Field               | What it means                                                                         |
| ------------------- | ------------------------------------------------------------------------------------- |
| `keyLabel`          | The name you gave the key when you made it                                            |
| `plan`              | The plan on the key: `free`, `starter`, `pro`, or `enterprise`                        |
| `callCount`         | How many requests this key has ever made                                              |
| `createdAt`         | When the key was made                                                                 |
| `lastUsedAt`        | When the key was last used                                                            |
| `monthlyUsage`      | This month's usage: `used`, `limit`, and when it `resetsAt`                           |
| `requestsPerSecond` | Per-second cap on the free plan. `null` on paid plans, which have no per-second limit |

## What errors mean

| Case                                    | Response           |
| --------------------------------------- | ------------------ |
| You sent no key                         | `401 Unauthorized` |
| The key is wrong or turned off          | `401 Unauthorized` |
| The key is fine but the plan is too low | `403 Forbidden`    |

## Good habits

* Keep API keys secret, like passwords.
* Use a different key for each app or environment when you can.
* Make a new key if you think an old one leaked.