> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kamui.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Each client calls the API with its own API key, sent in the x-partner-api-key header.

Every request, including `health.ping`, must carry your API key in the `x-partner-api-key` header.

```bash theme={null}
curl -X POST "https://api.kamui.finance/functions/v1/external-api/health.ping" \
  -H "Content-Type: application/json" \
  -H "x-partner-api-key: $KAMUI_API_KEY" \
  -d '{}'
```

## Key format

A key looks like `kmi_<id>_<secret>`:

* `kmi_`, then 12 lowercase base32 characters (`a`–`z`, `2`–`7`): this part is the key prefix;
* `_`, then 43 base64url characters: the secret.

A key is 60 characters long. After creation, Kamui sees only the prefix (`kmi_<id>`), so you can name a key to Kamui by its prefix without sharing the secret.

## Getting a key

Kamui issues the keys, one or more per client. The full key is shown once, when it is created. Store it in a secret manager right away. A lost key cannot be recovered; Kamui rotates it instead.

<Warning>
  Keep the key on your backend. Never put it in a browser, a mobile app, a public repository or a log line.
</Warning>

## Trying requests in these docs

Each endpoint page has a **Try it** playground: paste your key under **Authorization** and click **Send**. The API sends no CORS headers, so the playground sends the request, key included, through the documentation site's request proxy. Use a key you can rotate, and ask Kamui to rotate it if you pasted it on a shared computer.

## Rotation and revocation

* **Rotation:** Kamui issues a new key. The old key keeps working for a grace period that Kamui sets when it rotates (24 hours by default), then stops. Switch to the new key within the grace period.
* **Revocation:** Kamui can revoke a key at once, for example when a key may have leaked. Ask Kamui to revoke and replace a key you think is exposed.

## Failed authentication

A missing, malformed, unknown, revoked or expired key always answers the same response:

```json theme={null}
{ "error": "Unauthorized.", "code": "unauthorized", "requestId": "ea80702c-a332-4e32-922e-76bcb02e6156" }
```

with HTTP status `401`. The API checks the method first, then the key, then the action, so an unknown action also answers `401` until the key is valid.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.