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

# Authentication

> All API requests require a valid API key in the Authorization header.

```
Authorization: Bearer rw_your_api_key
```

***

## Getting an API key

1. Open your dashboard → **Account → Integration**
2. Click **New API key**, give it a name
3. Copy the key — it is shown **only once**
4. Under **Access**, select the point systems this key can interact with

<Warning>
  A key with no point systems assigned has no access to any data or actions. Always scope keys to the minimum required point systems.
</Warning>

***

## Scoping keys to point systems

Each API key is scoped to one or more point systems. Any request that references a `pointSystemId` not in that key's scope will be rejected with a `403`.

This lets you issue separate keys per application or environment:

| Key               | Scoped systems    | Use case               |
| ----------------- | ----------------- | ---------------------- |
| `rw_prod_...`     | Production system | Live app               |
| `rw_staging_...`  | Staging system    | CI / testing           |
| `rw_readonly_...` | Any system        | Dashboard integrations |

***

## Permission level

In addition to its point-system scope, every API key carries a **permission level**, chosen when you create the key (Account → Integration). It is one of:

| Permission | Unlocks                                                                                      |
| ---------- | -------------------------------------------------------------------------------------------- |
| `trigger`  | `POST /trigger` only                                                                         |
| `read`     | The read endpoints (`/leaderboard`, `/wallet`, `/activity`, `/rewards`, `/points`, `/score`) |
| `all`      | Both trigger and read endpoints                                                              |

Calling an endpoint the key isn't permitted for returns `403`. For example, a `read`-only key hitting `/trigger`, or a `trigger`-only key hitting `/leaderboard`.

***

## Key format

API keys always start with `rw_` followed by a 32-character hex string.

```
rw_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d
```

Keys are stored as a SHA-256 hash — Rewards never has access to the raw key after generation.

***

## Error responses

| Status | Message                                                           | Cause                                                   |
| ------ | ----------------------------------------------------------------- | ------------------------------------------------------- |
| `401`  | `Missing API key`                                                 | No `Authorization` header                               |
| `401`  | `Invalid API key format`                                          | Key doesn't start with `rw_`                            |
| `401`  | `Invalid API key`                                                 | Key not found                                           |
| `403`  | `This API key does not have access to the specified point system` | Key not scoped to that `pointSystemId`                  |
| `403`  | `This API key does not have read permissions`                     | `read` (or `all`) permission required for this endpoint |
| `403`  | `This API key does not have trigger permissions`                  | `trigger` (or `all`) permission required for `/trigger` |