**Platform -> API keys** in your admin sidebar.

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, can be held to the addresses of your servers, and every call made with it
is logged for 30 days.

You need the `view_api_keys` permission to open the screen and `manage_api_keys`
to make, change, rotate or revoke a key. Without `manage_api_keys` you see the
same screen with nothing to change.

## The list

The screen opens on the list alone, across its whole width, and shows no key in
full until you pick one. Each row shows the key's name and key id, its status,
what it may do, its calls over the last 7 days with how many failed, when it
ends, when it was made and when it was last used. A key whose old secret still
works after a rotation says so under its name.

Under the title the list counts the keys that are not revoked. Three more
counts appear when they are not zero, and each is a filter: the keys that stop
working within two weeks, the keys with failed calls this week, and the revoked
keys. Click one to see only those keys, click it again to see them all.

The search box finds a key by name or key id. The filter menu sorts the list
(newest, name, last used, most calls or most failures this week, ending
soonest) and narrows it by status, by whether it was called this week, never
used or had failures, and by a scope it holds. Revoked keys are hidden until
you ask for them, so the list shows what is in use.

Press `J` and `K` to move through the keys, and `Enter` to open one. A right
click on a row opens its usage or its calls directly, rotates the secret, starts
a new key like it, copies its name, key id or link, and revokes it.

## A key

Opening a key folds the list to a column on the left and shows the key beside
it. The address changes with it, so a link to a key opens on that key. `Esc`
or the cross folds the list back out, to the same search and filters.

The head of the key shows its name, its key id and a line with its status,
when it was last used, and until when its old secret still works after a
rotation. Under it a row of facts answers the first questions about any key:
its calls this week and how many failed, when it was last used, how many scopes
it holds, when it ends, and who made it when. **Rotate secret** sits on the
right, with the rest in the menu beside it.

### Key

What the key may do and from where, saved together with the dock at the bottom
of the screen. Only the fields you changed are sent.

| Field             | What it does                                                                                                                                                           |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name              | Which system holds it, so the list says what breaks when it goes.                                                                                                      |
| Scopes            | What the key may do, grouped by resource. Managing a resource includes reading it. Each scope says how many endpoints it opens and how often the key used it lately.   |
| Allowed addresses | Optional. One IPv4 or IPv6 address or CIDR range per line, at most 50. Calls from anywhere else are refused. The address the key was last called from is one click away. |
| Ends              | Optional. The key stops working at the end of that day in your timezone. Pick a day, 30, 90 or 365 days ahead, or no end.                                               |

A change applies to the next call, and the secret stays the same, so nothing
has to be redeployed. Every entry is checked before it is saved: an address
that is not a real address or range is refused rather than stored, so a typo
can never lock a key down without you noticing.

Beside the form a column says what the key can call and how to call it, with
the base URL and a `curl` to copy, and warns before you save:

- a scope you are taking away that the key used in the last 7 days, and how
  often, because those calls fail the moment you save
- a scope the key was refused for lacking in the last 7 days
- an allowlist that refuses the address the key was last called from
- an end date that has passed or is close

:::warning Removing a scope breaks callers immediately
A call that needs a scope you just removed comes back as `403` with
`insufficient_scope`. The warning in the side column names the scope and how
often it was used.
:::

### Usage

Calls, failed calls and response time over today, the last 7 days or the last
30, each against the period before it. The three figures are the tabs of one
chart. Under it, the endpoints the key called with their calls, failures and
average response time, and the failures grouped by status and error code with
the share of calls that failed, each with a link to what that error means.
Click an endpoint or a failure to see those calls.

### Calls

Every call made with the key over the last 30 days, newest first, fifty to a
page. Search by request id, path, error code or status, show only the failed or
the succeeded calls, or pick one endpoint. Open a call for its request id, when
it was made, the endpoint and its documentation, the answer, how long it took
and what sent it. **Export CSV** downloads every call that matches.

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

### Activity

Who made the key, every change to its name, scopes, addresses and end, every
rotation, every export of its calls and the revoke, with who did it. You need
`view_activity_logs` to see this tab.

## A new key

**New key** opens an empty key beside the list. Give it a name and at least one
scope, set its addresses and end if you want them, and create it with the dock.
**New key like this** on an existing key starts from its scopes and addresses,
for moving a system to a fresh key.

The full key is shown once, right after it is made, with the `Authorization`
header ready to copy. Store it in your secret manager before you close the
dialog.

:::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 secret.
:::

## Rotating

Rotating gives the key a new secret and keeps its scopes, addresses and
history. You choose how long the old secret keeps working beside the new one:

| The old secret      | For                                                        |
| ------------------- | ---------------------------------------------------------- |
| Stops now           | A secret that leaked. Calls with it fail from that moment. |
| Works one more hour | Enough to change the setting and deploy. The default.      |
| Works one more day  | A system that only picks up a new setting overnight.       |
| Works one more week | A system somebody else runs.                               |

While the old secret still works, the key shows until when, and when the old
secret was last used. **Stop the old secret now** in the menu ends it early,
once nothing uses it any more. Rotating again while an old secret still works
stops that one at once, so a key never has more than two secrets.

## Revoking

Revoking stops the key at once, including an old secret that still worked, and
cannot be undone. A revoked key stays on the list so its history and its calls
remain, and it can no longer change.

## In the older designs

Propper - OG and Tactical keep a table of the keys, a dialog to make one, and a
page of its own per key with its counters, a chart per day, its endpoints,
failures, recent calls and editable scopes. Rotating there stops the old secret
at once. Changing a key's name, addresses or end, rotating with a grace period,
searching and filtering the calls beyond the last 50, exporting them, starting
from a copy of a key, the warnings before saving and the Activity tab are only
in the standard design.