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

# Authentication

> Authenticate API requests and keep your secret key server-side

Every authenticated API request uses a secret key as a Bearer token. Use the
key for the merchant and mode you are working with. The Quickstart uses a
Sandbox key; Sandbox and Production use separate keys on the same API base URL.

## Create a key

Sign in using the Merchant Portal invitation or access link supplied to you.
Select the correct merchant and confirm that your user can manage API keys.
Start the [Quickstart](/guides/quickstart) once Sandbox access and your key are ready.
Portal sign-in and API Bearer authentication are separate.

1. In the Merchant Portal, select your merchant and open **Developers → API keys**.
2. Select **Sandbox** for testing or **Production** for live requests. Production
   key creation is available once your merchant is enabled for live processing.
3. Choose **Generate secret key**. Your Portal user needs permission to manage API keys.
4. Store the new value in your server-side secrets manager. It is **shown only once**.

Sandbox secret keys start with `api_test_sk_`; Production secret keys start with
`api_live_sk_`. A key selects the mode for API requests. Keep keys separate in
your application configuration, and never send a Production key from a test integration.

## Configure the key

Store the key in a server-side secrets manager or environment variable:

```bash theme={null}
export FLOWLIX_API_KEY="api_test_sk_example"
export FLOWLIX_BASE_URL="https://api.flowlix.eu"
```

The value above is deliberately synthetic. Replace it locally with your test
key and never paste the real value into source control, logs, screenshots, or
support messages.

## Send an authenticated request

```bash theme={null}
curl "$FLOWLIX_BASE_URL/v1/payments?limit=1" \
  -H "Authorization: Bearer $FLOWLIX_API_KEY"
```

The header format is exactly:

```http theme={null}
Authorization: Bearer api_test_sk_example
```

Requests without a valid key return `401 Unauthorized` with
`error.code: "invalid_api_key"`.

## Keep the key safe

<Warning>
  Call Flowlix only from your server. Never place a secret key in browser
  JavaScript, a mobile application, a public repository, or client-visible
  configuration.
</Warning>

* Keep separate credentials for each environment in your own system.
* Restrict access to the service that calls Flowlix.
* Redact the `Authorization` header from application and proxy logs.
* If a key may have been disclosed, revoke it in the Portal and contact Flowlix support.

## Replace or revoke a key

For a planned replacement, generate a new key in the same mode and use the
new key only for new operations. Idempotency is scoped to the API key as well
as the operation: the same `Idempotency-Key` under a different API key does not
protect against creating a second Payment, Refund, or Payout.

Keep retries of existing operations on their original API key, following
[Idempotency](/guides/idempotency). Resolve or reconcile outstanding operations
and verify the new key before retiring the old one. In **Developers → API keys**,
choose **Revoke key** for the old key and confirm with your current password.
Revocation can take up to a minute to take effect.

If the key is compromised, revoke it promptly. Reconcile any uncertain create
results; never automatically retry those creates under the new key. Contact
Flowlix support when you cannot establish whether an operation was created.

## Authentication and resource access

| HTTP  | `error.code`       | What to check                                                                                 |
| ----- | ------------------ | --------------------------------------------------------------------------------------------- |
| `401` | `invalid_api_key`  | The header is present, uses the `Bearer` scheme, and contains a valid current key.            |
| `404` | `object_not_found` | For a Payment or Payout lookup, the object ID belongs to the authenticated merchant and mode. |

A valid key for another mode does not grant access to the original mode's
objects. A Payment or Payout lookup outside the key's merchant and mode returns
`404 object_not_found`, just like an unknown object ID.

For the full response shape and retry rules, see [API errors](/guides/errors).