# API keys and roles

> Securing a key with an allowlist and signing, rotating it, and who in your team can do what.

Source: https://useroutegate.com/docs/concepts/api-keys

A key starts `rg_test_` or `rg_live_` and is shown once. Live and test are kept apart: a key only sees its own mode. Create keys under **Developers > API keys**, which needs a verified email. An owner who turned two-factor on is asked for a code entered within the last ten minutes.

## IP allowlist

A key can be limited to a list of addresses or CIDR ranges. A call from anywhere else is refused with `403 PERMISSION_DENIED`.

## Request signing

A key can require every request to be signed. Send two headers:

| Header                | Value                                                                                 |
| --------------------- | ------------------------------------------------------------------------------------- |
| `Routegate-Timestamp` | The current Unix time in seconds. Refused if more than five minutes off.              |
| `Routegate-Signature` | The hex HMAC-SHA256 of `<timestamp>.<raw body>`, keyed with the key's signing secret. |

A missing or wrong signature on such a key is `401 AUTH_REQUIRED`. Note that a request signature is the bare hex, while a [webhook signature](/docs/concepts/webhooks) under the same header name has the form `t=<unix>,v1=<hex>`.

## Rotating a key

Rotating gives you a new key and keeps the old one working for 24 hours, so you can swap it without downtime. Revoking stops a key at once.

## Who can do what

| Action                                      | Roles                 |
| ------------------------------------------- | --------------------- |
| Create and manage API keys                  | Owner, admin          |
| Add a webhook endpoint or rotate its secret | Owner                 |
| Change or remove a webhook endpoint         | Owner, admin          |
| Fund the wallet                             | Owner, admin, finance |
| Give the funding identity                   | Owner                 |

These are the built-in roles. A business can make its own roles under **Team**, and a role with the same permission can do the same, except the actions that name the owner.