> For the complete documentation index, see [llms.txt](https://hinkal-team.gitbook.io/hinkal/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hinkal-team.gitbook.io/hinkal/hinkal-partner/api-keys.md).

# API Keys

Each API key is a publishable and secret pair. This page covers formats, allowed origins and the key lifecycle.

Every key is a pair: a **publishable** key and a **secret** key. Both credit calls to your company and apply your fee. They differ only in where they're safe to use.

|              | Publishable                                                     | Secret                                           |
| ------------ | --------------------------------------------------------------- | ------------------------------------------------ |
| Format       | `hk_pk_live_` + 64 hex characters                               | `hk_sk_live_` + 64 hex characters                |
| Use it in    | Browser code                                                    | Your servers only. Keep it in a secrets manager. |
| Origin check | The request's `Origin` must exactly match one on the key's list | None                                             |
| Effect       | Attribution and your fee                                        | Attribution and your fee                         |

Every key is live. There's no test mode or sandbox key, so use a separate key per environment.

***

### Create a key

[Owners, Admins and Developers](/hinkal/hinkal-partner/getting-started/team-and-roles.md) can create keys from **API Keys** or the [Dashboard](/hinkal/hinkal-partner/dashboard.md). Creating or changing a key needs a [recent sign-in](/hinkal/hinkal-partner/settings-and-security.md#recent-sign-in).

1. Choose **New API key** and give it a name of up to 50 characters, such as `Production backend` or `Web app`.
2. The *API key created* screen shows both full keys. It closes only when you choose **Done**.
3. Put the secret key in your secrets manager.

Use one key per app or environment. [Analytics](/hinkal/hinkal-partner/analytics.md#breakdowns) breaks volume down by key, so that's how you tell them apart later.

***

### Copy a key again

* **Publishable key:** anyone on the team can copy it from the key list.
* **Secret key:** Owners, Admins and Developers can copy it again after a [recent sign-in](/hinkal/hinkal-partner/settings-and-security.md#recent-sign-in).

***

### Turn off, rename or revoke

* **Turn off** with the **Active** switch. Requests that send it then fail with `401 Invalid API key` (see [Errors and Limits](/hinkal/hinkal-partner/errors-and-limits.md#api-errors)). Switch it back on any time.
* **Rename** from the key list. The new name shows in Analytics and in new CSV exports.
* **Revoke** permanently disables both halves of the pair, and the key leaves the list. Its past volume stays in Analytics and CSV exports under its old name.

{% hint style="danger" %}
Revoking can't be undone. Apps still sending the key start getting `401` within a minute.
{% endhint %}

***

### Limits

* 10 keys per company. Keys that are turned off still count. Revoked keys don't.
* 10 allowed origins per key.

***

### Allowed origins

A publishable key only works from the origins on its list. **New keys start with an empty list, so a publishable key returns `403` until you add one.** Secret keys ignore the list.

Add origins on the API Keys page, one at a time. Each one is reduced to scheme, host and port:

| You enter                          | Saved as                                                                                 |
| ---------------------------------- | ---------------------------------------------------------------------------------------- |
| `app.example.com`                  | `https://app.example.com`                                                                |
| `https://app.example.com/checkout` | `https://app.example.com`                                                                |
| `http://localhost:3000`            | `http://localhost:3000`. Plain HTTP works for `localhost`, `127.0.0.1` and `[::1]` only. |
| `http://app.example.com`           | Rejected. Use HTTPS.                                                                     |
| `https://*.example.com`            | Rejected. Wildcards aren't supported.                                                    |

The match is exact. `https://example.com`, `https://www.example.com` and `https://app.example.com:8443` are three different origins, and so are `http://localhost:3000` and `http://localhost:5173`. Add each one you serve from, including staging and preview domains.

Server-side calls usually send no `Origin` header, so a publishable key fails there with `403`. Use the secret key on servers.

***

### When changes reach the API

The API caches each key for up to 60 seconds. Turning a key off or on, revoking it, editing its origins and changing your fee can take that long to apply.