---
agentTools:
  projectIndex: https://docs.ninepay.com.br/llms.txt
  projectSearch: https://docs.ninepay.com.br/agentSearch?query=term1%20term2
---

# Authentication

Every call to the NinePay API is authenticated with an API key. You generate keys in the dashboard, and they have an automatic lifecycle: keys that go unused are disabled and, later, expired.

## How to authenticate

Send the key in the `Authorization` header, using the `Bearer` scheme:

```bash
curl https://payments.cefis.com.br/api/v1/customers \
  -H "Authorization: Bearer $NINEPAY_TOKEN" \
  -H "Accept: application/json"
```

Without a key, or with a disabled, expired or deleted key, the API responds with 401.

## Format

| Prefix | Environment |
| --- | --- |
| `sk_prod_…` | Production |
| `sk_hmlg_…` | [Sandbox](/docs/sandbox-en) |

Keys created before the new Integrations screen use the old format, without a prefix, and keep working the same way. They follow the lifecycle described below like any other key.

## Generating a key

1. In the dashboard, open **Integrações** (Integrations) and go to the **Chaves de API** (API keys) tab.
2. Create the key with a name that says where it is used (for example, "Website" or "ERP").
3. Optionally, choose an expiration date and time.
4. Copy the key and store it somewhere safe.

> 🚧 The key is shown only once
>
> After you close the window, neither you nor NinePay can see the key again, because we only store a hash of it. If you lose it, generate a new one.

Each company can have up to 10 keys.

## Rotating a key

Rotate a key without taking your integration down:

1. Generate a new key.
2. Update your system to use the new key.
3. Disable the old key in the dashboard.
4. Check that nothing broke. If something does, re-enable the old key and investigate.
5. Once everything works, delete the old key.

## Automatic lifecycle

An unused key goes through these states:

| State | When | Can it be undone? |
| --- | --- | --- |
| Enabled | In use, or unused for less than 3 months | |
| Disabled | 3 months without use | Yes, re-enable it in the dashboard |
| Expired | 6 months without use | No, generate a new key |

- The account owner receives an email 7 days before the key is disabled for lack of use, and another one on the day. Expiration, whether after 6 months without use or on the date you chose, has no warning.
- Every call authenticated with the key counts as use and restarts the count.
- If you set an expiration date, the key stops working on that date, regardless of use.

## Best practices

- Never put the key in code that runs in the browser or in a mobile app: anyone who downloads the app or opens the page source can read it. Call the API from your server.
- Store the key in an environment variable (such as `NINEPAY_TOKEN` in the examples), not in your code or repository.
- Use one key per integration. That way you can disable or rotate one without affecting the others, and see which ones are in use.
- If you suspect a key has leaked, disable it and generate a new one.