> For the complete documentation index, see [llms.txt](https://docs.omni.integratedcommerce.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.omni.integratedcommerce.io/get-started/authentication.md).

# Authentication

API keys, how key scope is enforced, and the sandbox and production key formats.

All API requests must be authenticated using an API key. The API key should be included in the `x-api-key` header of each request.

## API key format

```http
x-api-key: <api-key>
```

## Resource scope

An API key grants access only to the resources owned by its merchant. Every resource identifier you supply - transaction IDs, account holder IDs, payment method tokens, subscription IDs, settlement IDs - is resolved within the scope of the merchant that owns the API key.

Supplying an identifier that belongs to a different merchant produces the same not-found response as an identifier that does not exist at all. Responses do not distinguish between the two cases, so a resource ID cannot be used to determine whether it exists under another merchant.

## Environments

Separate API keys identify the sandbox and production environments. The base URL for both environments is the same, but the keys are different.

| Environment | Key format                 | Use for                 |
| ----------- | -------------------------- | ----------------------- |
| Sandbox     | `key_test_<ULID>.<secret>` | Development and testing |
| Production  | `key_live_<ULID>.<secret>` | Live production traffic |

Send the complete key, including the secret after the dot. Existing legacy keys without a dot remain supported until revoked.

The base URL for both is:

```
https://api.omni.integratedcommerce.io/v1
```

{% hint style="danger" %}
Because both environments share a base URL, the key is the only thing separating test traffic from live traffic. Keep production keys in a secrets manager, never in source control, client-side code, or configuration checked into a repository.
{% endhint %}

## Authentication failures

If authentication fails because of an invalid or missing API key, you will receive a `401 Unauthorized` response. Check the response message for more details.

## Next steps

* [Request conventions](/get-started/conventions.md) - identifiers, amounts, and currencies
* [Errors and rate limits](/get-started/errors-and-rate-limits.md) - rate limit headers and error shapes