Your API key
The API key is the credential your systems use to identify themselves to Hablame. Here you see what it looks like, who can create it, which options it has at creation and how to look after it.
5 min readReviewed on
What a key looks like
An API key is a string like this one (here, an example placeholder):
hk_TU_API_KEY- A real one starts with
hk_and continues with 32 lowercase hexadecimal characters. It is case-sensitive: with uppercase letters the API answersAUTH_INVALID_KEY. - It is shown in full only once, right when you create it. Hablame stores only a fingerprint of the key, not the key itself: if you lose it, it cannot be recovered. Delete it and create another.
- In the Cloud list you only see the beginning and the end of each key, just enough to tell them apart.
Who can create one
| Action | Who can |
|---|---|
| Create a key, with or without an expiry | Only the owner of the organization. |
| Delete a key | Whoever created it, or the owner or an administrator. |
If your role does not reach an option, Cloud shows it turned off and tells you who can. You do not have to guess why you cannot select it.
How to create one
- 01Open “API keys” in Cloud
It is in the developers area of cloud.hablame.co. If your role cannot create keys, the screen tells you so.
- 02Press “Generate key” and fill in the details
Write a description, choose the cost center and the expiry.
- 03Choose the permissions
Select the services your integration needs (each one is granted in full), the account capabilities only if they are needed and, if you want, the networks it can be used from.
- 04Copy the key and store it
Cloud shows it only once. Copy it to your secret manager before closing the window.
What you choose when creating one
Descripción- Required, up to 200 characters. It helps you remember what you created it for, for example “Checkout backend, production”.
Centro de costos- Required. The key’s usage is attributed to that cost center. It cannot be changed afterwards.
Servicios- The services the key can use, each one in full: with the URL Shortener the key lists, creates (each creation is charged), edits, deletes and restores links, and with Storage it sees everything, files and downloads included. There are no read-only permissions within a service. If you select none, the key can use none. “All services” selects the ones that exist today: a service launched later is not included, and to use it you have to create another key.
Capacidades- Permissions over the account, apart from the services, that are granted only if you select them:
account(read balance and billing, sensitive information) anddirectory(read organization data, cost centers and users, with personal data). Selecting “All services” includes none of them. Caducidad- 30, 60, 90 or 180 days, one year or no expiry. Cloud recommends rotating keys every 90 days and leaving “no expiry” only for integrations whose rotation has a process outside the portal.
Redes permitidas- Optional. One IP (
203.) or one IP range (0. 113. 7 198.) per line, up to 20. If you leave it empty, the key works from any network. If you set networks, from any other the API answers51. 100. 0/ 24 403 AUTH_IP_NOT_ALLOWED. It cannot be changed afterwards.
A key is not edited
A key is created and deleted; nothing else. If you need other permissions, create a new key, switch your integration to it and delete the old one. That way nobody changes the permissions of a credential that is already spread across your servers without you knowing.
Each organization can have up to 20 active keys at a time. When the maximum is reached, Cloud asks you to delete one before creating another.
How to delete one
From the same Cloud screen, “Delete key”. Cloud asks you to type the key’s description to confirm. A deleted key is disabled forever and cannot be activated again.
The API takes up to 30 seconds to stop accepting a deleted key, because it keeps the verification result for a moment. If the key was exposed, delete it immediately and tell support.
How to look after it
- Keep it in a secret manager and read it as an environment variable when your application starts.
- Do not commit it to a repository, paste it into a chat or send it by email, not even to support: your organization name is enough to identify your account.
- Use one key per integration and only with the services it needs: each service is granted in full, so a key with the URL shortener can also create links, which are charged.
- If you can, restrict the networks it works from.
- If someone with access to the key leaves your team, create a new key and delete the old one. A key created by someone who is no longer in the organization keeps working until you delete it.
The detail of how the API verifies a key on each request is in the authentication guide.
For technical questions, email developers@hablame.co. If you have a production incident, message us on WhatsApp at +57 319 660 0002, 24/7.