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

# Authentication

> Authenticate requests to the storekit API with an API key: which header to send, the key format and checksum, what a refused key returns, and how to keep keys safe.

Every request to the API is authenticated with an API key. A key belongs to one account and gives access to that account's data only.

## Send Your Key

Send the key in the `Authorization` header as a bearer token:

```bash theme={null}
curl https://api.storekit.com/v1/orders \
  -H "Authorization: Bearer $API_KEY"
```

The `X-API-Key` header is accepted as well:

```bash theme={null}
curl https://api.storekit.com/v1/orders \
  -H "X-API-Key: $API_KEY"
```

Send one or the other. If a request carries both, the key in `X-API-Key` is the one that is used.

A key is never accepted in the URL or in the request body.

## Key Format

```
foro_live_<secret>_<checksum>
```

| Part | Content |
| - | - |
| `foro_live_` | A fixed prefix. `live` is the environment, and the only one issued today. |
| `<secret>` | 64 lowercase hexadecimal characters. |
| `<checksum>` | 8 lowercase hexadecimal characters: the CRC32 of everything before the last underscore. |

A key is 83 characters long. An example with a made-up secret, which is not a working key:

```
foro_live_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef_cc90fca5
```

Treat the whole string as the key and store it as it is. Allow at least 255 characters where you store it, so a later format fits.

### Check a Key Before You Store It

The checksum is not a secret. It lets you catch a truncated or mistyped key without calling the API:

```javascript theme={null}
const zlib = require('node:zlib');

const isWellFormedApiKey = apiKey => {
    const match = /^(foro_live_[0-9a-f]{64})_([0-9a-f]{8})$/.exec(apiKey);

    if (!match) {
        return false;
    }

    const [, keyWithoutChecksum, checksum] = match;

    return zlib.crc32(keyWithoutChecksum).toString(16).padStart(8, '0') === checksum;
};
```

A key that passes this check can still be refused: it may be revoked, expired or never issued. A key that starts with `foro_live_` and fails it is always refused. The check is for `foro_live_` keys only: an [older key](#older-keys) has no checksum, so do not use it to reject one.

### Older Keys

Keys created before the checksum was added have no checksum. Most are `sk_live_` followed by 64 hexadecimal characters, and the earliest are 64 hexadecimal characters with no prefix. Both kinds keep working, are sent in the same headers and do not need to be replaced. The check above does not apply to them, so accept them as they are.

## Create a Key

A key is created for an account by a member of that account who has access to all of its stores. The account's plan has to include API keys.

1. In the dashboard, open **Developers & AI**.
2. On the **API keys** card, select **Manage API keys**.
3. Select **Create API Key**.
4. Enter a **Name** that says what will use the key, and choose its **Access** and when it **Expires**.
5. Copy the key and store it somewhere safe.

* **The key is shown once**, when it is created. Only a hash of it is stored, so it cannot be shown again. If you lose it, create a new one.
* The key list shows each key's name and, in the **Key** column, its first 18 characters, so you can tell your keys apart.
* **Expires** is set to **90 days** unless you choose **30 days**, **1 year**, **Custom date** or **No expiry**.
* The **Last used** column shows when each key was last used, to within about a minute.

## When a Key Is Refused

A request without a key, or with a key that is not accepted, is answered with `401` and an [error](https://storekit.com/docs/developers/api/errors) of type `authentication_error`:

| Situation | `code` | `WWW-Authenticate` header |
| - | - | - |
| No key was sent | `api_key_missing` | `Bearer` |
| The key was not accepted | `api_key_invalid` | `Bearer error="invalid_token"` |

```json theme={null}
{
    "error": {
        "type": "authentication_error",
        "code": "api_key_invalid",
        "message": "The API key provided is not valid.",
        "param": null,
        "doc_url": "https://docs.storekit.com/developers/api/errors#api_key_invalid",
        "request_id": "req_019a8f3b2c4d7e6f8a9b0c1d2e3f4a5b"
    }
}
```

`api_key_invalid` is the same answer for a mistyped key, a key that was never issued, a revoked key and an expired key. The response does not say which, so that it tells nothing to someone guessing keys. If a key that used to work starts answering `401`, check its **Status** and **Expires** columns in the key list to see whether it has expired or been revoked.

A `401` will not succeed when retried with the same key. Do not retry it.

A key that is valid but not allowed to make a particular request is answered with `403`, not `401`. See [`scope_insufficient`](https://storekit.com/docs/developers/api/errors#scope_insufficient) and [`permission_denied`](https://storekit.com/docs/developers/api/errors#permission_denied).

## Keep Your Key Safe

A key gives access to an account's data, so treat it like a password.

* **Call the API from your server only.** Never put a key in a web page, a mobile app or anything else that is delivered to a user's device, where it can be read.
* **Keep it out of source control.** Load it from an environment variable or a secret manager. Do not paste it into code, tickets, chat or support requests. Support never needs your key: send the [request ID](https://storekit.com/docs/developers/api/errors#request-ids) instead.
* **Use one key for each integration and environment**, named after what uses it, so that one can be revoked without stopping the others.
* **Do not log it.** If you need to refer to a key in a log, log its first 18 characters, which is what the key list shows.

### Rotate a Key

1. Create a new key.
2. Deploy it to everything that uses the old one.
3. Check in the key list that the old key is no longer being used.
4. Revoke the old key.

Because a key expires after 90 days by default, plan to do this before the expiry date.

### If a Key Leaks

Select **Revoke Key** on its row in the key list straight away, then create a new one. A revoked key stops working within a minute and cannot be restored.

### Find Leaked Keys

To scan your own code and logs for keys, match:

```
foro_live_[0-9a-f]{64}_[0-9a-f]{8}
```

A match is a real key only if its checksum holds, which is the check shown above. Older keys match `sk_live_[0-9a-f]{64}`, or 64 hexadecimal characters alone, and cannot be verified offline.


## Related topics

- [Authentication](https://storekit.com/docs/developers/mcp/authentication.md)
- [Email Deliverability](https://storekit.com/docs/guides/notifications/email-deliverability.md)
- [Security Policy](https://storekit.com/docs/privacy-security/security-policy.md)
- [Connect Other Clients](https://storekit.com/docs/guides/ai/connect/other-clients.md)
- [Connect Claude Code](https://storekit.com/docs/guides/ai/connect/claude-code.md)


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