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:

Shell

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

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

In the dashboard, open Integrações (Integrations) and go to the Chaves de API (API keys) tab.
Create the key with a name that says where it is used (for example, "Website" or "ERP").
Optionally, choose an expiration date and time.
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:

Generate a new key.
Update your system to use the new key.
Disable the old key in the dashboard.
Check that nothing broke. If something does, re-enable the old key and investigate.
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.