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

# Authentication

> API keys, common headers and authentication responses of the iMoney Encaissement API.

The iMoney Encaissement API is a JSON REST API, available at the base URL
`https://i-pay.money/api/v1`. Except for the single public operation mentioned below, every call
authenticates with the secret key of the account matching the target environment, and carries the
four common headers described here.

## Required headers

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
Content-Type: application/json
Authorization: Bearer IPAY_SECRET_KEY
Ipay-Target-Environment: sandbox
Ipay-Payment-Type: mobile
```

| Header | Rule |
| - | - |
| `Content-Type` | Use exactly `application/json`. |
| `Authorization` | Use the `Bearer` prefix followed by the secret key. |
| `Ipay-Target-Environment` | `sandbox` or `live`, consistent with the key. |
| `Ipay-Payment-Type` | `mobile` for `POST /payments` (the only payment method supported by this operation). Other methods go through [payment by link](https://docs.i-pay.money/en/api-reference/payment-by-link/create-a-payment-link.md). |

## API keys and environments

The dashboard (**Développeurs → Clés API**, i.e. Developers → API keys) provides a public key and a secret key for
each environment:

| Key | Format | Use |
| - | - | - |
| Public key | `pk_sandbox_…` / `pk_live_…` | Reserved for integrations explicitly designed for a client-side key, such as the JavaScript SDK. |
| Secret key | `sk_sandbox_…` / `sk_live_…` | API calls made by your server, with `Authorization: Bearer`. |

Sandbox and Live are two fully separate accounts, each with its own key pair. A Sandbox key
used with `Ipay-Target-Environment: live` fails with an authentication error (and
vice versa): the two environments never silently stand in for each other.
Plan for one configuration per environment (same base URL, separate keys and header)
rather than a simple boolean switch in your code.

## Protecting your keys

* Store the secret key in a secrets manager or a server-side environment variable.
* Never embed it in front-end JavaScript, a mobile app, a screenshot or
  a Git repository.
* Use different keys for Sandbox and Live, and never reuse a Live key in a
  test environment.
* After regenerating a key, update the services concerned before removing the old
  configuration.
* Log the reference and the HTTP code, but never the `Authorization` header.

## Authentication responses

Header checks run in a fixed order on every authenticated operation: the
first unmet condition determines the response. The exact order and the literal messages are
detailed in [Errors](https://docs.i-pay.money/en/api-reference/errors.md).

| Code | Meaning |
| - | - |
| `400` | Missing header, environment or payment type not allowed, missing `Bearer` format. |
| `401` | No valid key matches the requested environment. |
| `403` | The account is not validated for the requested environment. |
| `406` | The `Content-Type` is not `application/json`. |

A Sandbox key used with `Ipay-Target-Environment: live` (or the reverse) is syntactically
valid: it fails with `401`, not `400`.

## Public operation

Only one operation of this API requires no key and no authentication header:
[Retrieve a payment link](https://docs.i-pay.money/en/api-reference/payment-by-link/retrieve-a-payment-link.md)
(`GET /external_payments/{reference}`). Anyone who knows the reference can call it:
use a random, high-entropy reference, never a sequential identifier.

## Webhooks

iMoney Encaissement sends the secret you configured in the `Secret-Hash` header of its
notifications. It is a static shared value, to be compared with your own secret on the server side,
not an HMAC signature computed on the request body. The full setup is described
in [Webhooks](https://docs.i-pay.money/en/guides/webhooks.md).


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