Authentication
How to create, use, rotate and protect CartaFlow API keys.
Every request to the API carries an API key in the Authorization header. The key identifies your account: everything you create with it belongs to that account and is charged to its balance.
The key
Every key starts with cf_live_ and uses the URL https://api.cartaflow.com.br/v1. With it, letters and verifications are printed, posted and charged to the account balance. To check a letter at no cost, use POST /v1/letters/quote: it validates everything and returns the price, without creating or charging anything.
Keys only exist once CartaFlow has approved the company's account.
Create a key
- In the CartaFlow dashboard, which is in Portuguese, open Desenvolvedores > Chaves de API (Developers > API keys).
- Give the key a name that says where it will be used, such as "ERP billing".
- Copy the key. It is shown only once: after that, the dashboard shows only its first and last characters.
- Store the key in an environment variable or a secrets manager on your server.
You can have several active keys at once, for example one per system that integrates with CartaFlow. This also lets you rotate a key without stopping your integration.
Use the key
Send the key in the Authorization header, after the word Bearer:
curl https://api.cartaflow.com.br/v1/balance \
-H "Authorization: Bearer $CARTAFLOW_API_KEY"To find out which account a key belongs to, call GET /v1/account. This helps in integrations that serve many customers, such as an ERP: each customer enters their own key, and your system confirms whose it is.
Keep the key on your server
The key gives access to your balance and to your recipients' data. So:
- Call the API only from your server. The API does not accept requests from browsers (it does not allow CORS), so a key placed in website code does not even work.
- Never put the key in a mobile app, in code that runs in the browser, in your repository or in logs.
- If your app needs to create letters, it calls your server, and your server calls CartaFlow.
A key leaked
Revoke the key right away in the dashboard, under Desenvolvedores > Chaves de API. Revocation takes effect immediately: any request with the revoked key gets a 401. Then create a new key and update your server.
Rotate a key
To replace a key without interrupting your letters:
- Create a new key in the dashboard.
- Update the environment variable on your server and deploy the change.
- Check that calls work with the new key.
- Revoke the old key in the dashboard.
Authentication errors
| HTTP | error.code | What happened | How to fix it |
|---|---|---|---|
| 401 | api_key_missing | The request has no Authorization header. | Send Authorization: Bearer followed by your API key. |
| 401 | api_key_invalid | The key does not exist or is mistyped. | Copy the key again from the dashboard. It starts with cf_live_. |
| 401 | api_key_revoked | The key was revoked in the dashboard. | Create a new key and update your system's environment variable. |
| 403 | account_suspended | The account is suspended and cannot create mailings. | Contact CartaFlow support from the dashboard. |
The format of every error response is in Errors.