**Configuration -> API keys** in your admin dashboard.

An API key lets your own website or back office act on behalf of your firm
through the [Propper API](/docs/api). Each key carries only the scopes you grant
it, and every request made with it is logged.

## Creating a key

Click **New key** and fill in:

| Field        | What it does                                                                        |
| ------------ | ----------------------------------------------------------------------------------- |
| Name         | How you recognise it later. Name it after the integration, not the person.          |
| Scopes       | What the key may do. Grant the minimum it needs.                                    |
| IP allowlist | Optional. Only these addresses may use the key. One address or CIDR range per line. |
| Expires on   | Optional. The key stops working at the start of that day.                           |

Scopes are grouped by resource, one collapsed section each. The switch on a
section grants or revokes everything in it at once; open the section to pick
individual actions. A half-filled switch means part of that section is granted.

The secret is shown once, right after you create it. Copy it into your secret
manager before you leave the page.

:::danger There is no way to see it again
We store only a hash of the secret, so nobody, including us, can read it back. If
it is lost, rotate the key.
:::

## Reading the list

| Column        | Meaning                                                                      |
| ------------- | ---------------------------------------------------------------------------- |
| Key           | The key id, the part that is safe to share when asking for help              |
| Scopes        | How many scopes this key holds. Open the key to see which ones               |
| Last used     | When it last made a request                                                  |
| Requests (7d) | Volume over the last week, with the last 24 hours and error count underneath |

A rising error count usually means a scope is missing or a secret is out of date
somewhere.

## Opening a key

Click the name of a key to open its own page. That is where the detail lives, so
the list stays readable as the number of scopes grows.

| Section       | What it shows                                                                                                |
| ------------- | ------------------------------------------------------------------------------------------------------------ |
| Counters      | Calls over the last 24 hours, 7 days and 30 days, how many of each failed, and average and p95 response time |
| Calls per day | The last 14 days as a bar per day, with the failed share in red                                              |
| Endpoints     | Which endpoints this key called over the last 7 days, with calls, errors and average response time           |
| Failures      | Failed calls over the last 7 days grouped by status and error code, with the last time each occurred         |
| Recent calls  | The last 50 calls, newest first, with the request id. Switch to **Errors only** to see just the failures     |
| Scopes        | Everything this key may do, editable in place                                                                |
| Key details   | Base URL, environment, rate limit, IP allowlist, expiry, last use and who created it                         |

Request history is kept for 30 days.

:::tip Quote the request id
Every call has a request id, copyable from the recent calls table. It is the
fastest way for us to find one specific request when you open a ticket.
:::

## Changing scopes

The key page has the same sectioned picker as the create dialog. Flip the
switches you need and click **Save scopes**. The change applies to the next
call, and the secret stays the same, so nothing has to be redeployed.

:::warning Removing a scope breaks callers immediately
A call that needs a scope you just removed starts coming back as `403` with
`insufficient_scope`. Check the endpoints list first to see what the key is
actually using.
:::

Scopes cannot be changed on a revoked key. Every change is recorded in the
activity log, with the old and the new set.

## Rotating

Rotating generates a new secret and the current one stops working immediately.
Anything still using the old secret starts failing at once.

:::tip Switching over without downtime
Create a second key with the same scopes, deploy it, confirm traffic has moved
across in the requests column, then revoke the first one.
:::

## Revoking

Revoking takes effect immediately and cannot be undone. Revoked keys stay in the
list so the audit trail and their request history remain intact.

## Permissions

Two permissions control this page, both assignable per role:

- `view_api_keys` - see the list, the key pages and their traffic.
- `manage_api_keys` - create, change scopes, rotate and revoke.

Creating, changing scopes, rotating and revoking are all recorded in the activity
log with the user who did it.