> ## 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.

# Integration

> Manage API keys for connecting external applications to Rewards.

The Integration page (under **Account → Integration**) is where you manage API keys for connecting external applications to Rewards.

***

## API keys

Each API key authenticates requests to the Rewards API. Keys are prefixed with `rw_` and stored as a one-way hash — the raw key is shown **only once** at creation time.

### Creating a key

1. Dashboard → **Account → Integration** → **New API key**
2. Give the key a descriptive name (e.g. `Production Oniria`, `Staging`)
3. Choose a **permission level** (see below)
4. Copy the key immediately — it cannot be retrieved after closing the dialog
5. Under **Access**, select the point systems this key can interact with

### Permission level

Every key is created with one of three permission levels, controlling which endpoints it can call:

| Permission | Endpoints it unlocks                                                                         |
| ---------- | -------------------------------------------------------------------------------------------- |
| `trigger`  | `POST /trigger` only (credit points, no reads)                                               |
| `read`     | Read endpoints only: `/leaderboard`, `/wallet`, `/activity`, `/rewards`, `/points`, `/score` |
| `all`      | Every endpoint — both trigger and read                                                       |

A key calling an endpoint outside its permission gets a `403` (e.g. `This API key does not have read permissions`). Pick the narrowest level that covers what the integration needs: a server that only awards points should use a `trigger` key; a dashboard or widget that only displays data should use a `read` key.

### Scoping keys

The **Access** dropdown controls which point systems a key can read and write.

* A key with **no point systems selected** has no access to any data or actions
* Scope each key to the minimum required systems
* Create separate keys for production, staging, and read-only integrations

### Revoking a key

Click **Delete** next to a key to revoke it immediately. Any requests using that key will return `401`.

***

## Finding your Point System ID

Your Point System ID is required for all API calls. You can find it in:

**Settings → General** — shown as both a short identifier (4 characters) and the full UUID, each with a copy button.

Use the full UUID in API calls.

***

## Security recommendations

<Warning>
  Store your API key in environment variables, never in source code.
</Warning>

* Use separate keys per environment (production / staging / local)
* Rotate keys periodically or immediately if you suspect exposure
* Scope keys to only the point systems they need access to

```bash theme={null}
# .env
REWARDS_API_KEY=rw_your_api_key
REWARDS_POINT_SYSTEM_ID=your-point-system-uuid
```

```ts theme={null}
// Never do this:
const API_KEY = "rw_384c65cdd3f5ff16..."; // hardcoded ❌

// Do this:
const API_KEY = process.env.REWARDS_API_KEY; // environment variable ✅
```