Tu clave de API
La clave de API es la credencial con la que tus sistemas se identifican ante Hablame. Aquí ves cómo es, quién puede crearla, qué opciones tiene al crearla y cómo cuidarla.
5 min de lecturaRevisado el
Crea tu clave en Cloud
Entra a Cloud y abre «Claves API». Si todavía no tienes cuenta, regístrate.
Cómo es una clave
Una clave de API es una cadena como esta (aquí, un marcador de ejemplo):
hk_TU_API_KEY- La real empieza por
hk_y sigue con 32 caracteres hexadecimales en minúscula. Distingue mayúsculas: con mayúsculas la API respondeAUTH_INVALID_KEY. - Se muestra completa una sola vez, justo al crearla. Hablame guarda solo una huella de la clave, no la clave: si la pierdes no se puede recuperar. Elimínala y crea otra.
- En la lista de Cloud solo ves el comienzo y el final de cada clave, lo justo para reconocer cuál es cuál.
Quién puede crearla
| Acción | Quién puede |
|---|---|
| Crear una clave, con o sin caducidad | Solo el propietario de la organización. |
| Eliminar una clave | Quien la creó, o el propietario o un administrador. |
Si tu rol no alcanza para una opción, Cloud te la muestra apagada y te dice quién sí puede. No hace falta que adivines por qué no puedes marcarla.
Cómo crearla
- 01Abre «Claves API» en Cloud
Está en el área de desarrolladores de cloud.hablame.co. Si tu rol no puede crear claves, la pantalla te lo avisa.
- 02Pulsa «Generar clave» y completa los detalles
Escribe una descripción, elige el centro de costo y la caducidad.
- 03Elige los permisos
Marca los servicios que necesita tu integración (cada uno se da completo), las capacidades de la cuenta solo si hacen falta y, si quieres, las redes desde las que puede usarse.
- 04Copia la clave y guárdala
Cloud la muestra una sola vez. Cópiala a tu gestor de secretos antes de cerrar la ventana.
Qué eliges al crearla
Descripción- Obligatoria, de hasta 200 caracteres. Sirve para que recuerdes para qué la creaste, por ejemplo «Backend de checkout, producción».
Centro de costos- Obligatorio. El consumo de la clave queda atribuido a ese centro de costo. No se puede cambiar después.
Servicios- Los servicios que la clave puede usar, cada uno completo: con el Acortador de URLs la clave lista, crea (cada alta se cobra), edita, borra y restaura enlaces, y con Almacenamiento ve todo, archivos y descargas incluidos. No hay permisos de solo lectura dentro de un servicio. Si no marcas ninguno, la clave no puede usar ninguno. «Todos los servicios» marca los que existen hoy: un servicio que se lance después no queda incluido, y para usarlo hay que crear otra clave.
Capacidades- Permisos sobre la cuenta, aparte de los servicios, que solo se conceden si los marcas:
account(consultar saldo y facturación, información sensible) ydirectory(leer datos de la organización, centros de costo y usuarios, con datos personales). Marcar «Todos los servicios» no incluye ninguno. Caducidad- 30, 60, 90 o 180 días, un año o sin caducidad. Cloud recomienda rotar las claves cada 90 días y dejar «sin caducidad» solo para integraciones cuya rotación tenga un proceso fuera del portal.
Redes permitidas- Opcional. Una IP (
203.) o un rango de IP (0. 113. 7 198.) por línea, hasta 20. Si la dejas vacía, la clave funciona desde cualquier red. Si pones redes, desde cualquier otra la API responde51. 100. 0/ 24 403 AUTH_IP_NOT_ALLOWED. No se puede cambiar después.
Una clave no se edita
Una clave se crea y se elimina; nada más. Si necesitas otros permisos, crea una clave nueva, cambia tu integración para usarla y elimina la anterior. Así nadie cambia los permisos de una credencial que ya está repartida por tus servidores sin que te enteres.
Cada organización puede tener hasta 20 claves activas a la vez. Al llegar al máximo, Cloud pide eliminar alguna antes de crear otra.
Cómo eliminarla
Desde la misma pantalla de Cloud, «Eliminar clave». Cloud te pide escribir la descripción de la clave para confirmar. Una clave eliminada queda inhabilitada para siempre y no se puede volver a activar.
La API tarda hasta 30 segundos en dejar de aceptar una clave eliminada, porque guarda por un momento la respuesta de la verificación. Si la clave quedó expuesta, elimínala de inmediato y avisa a soporte.
Cómo cuidarla
- Guárdala en un gestor de secretos y léela como variable de entorno al arrancar tu aplicación.
- No la subas a un repositorio, no la pegues en un chat y no la envíes por correo, ni siquiera a soporte: para identificar tu cuenta basta el nombre de tu organización.
- Usa una clave por integración y solo con los servicios que necesita: cada servicio se da completo, así que una clave con el acortador también crea enlaces, que se cobran.
- Si puedes, limita las redes desde las que funciona.
- Si alguien con acceso a la clave deja tu equipo, crea una clave nueva y elimina la anterior. Una clave creada por alguien que ya no está en la organización sigue funcionando hasta que la elimines.
El detalle de cómo la API verifica una clave en cada petición está en la guía de autenticación.
Para dudas técnicas escribe a developers@hablame.co. Si tienes una incidencia en producción, escribe por WhatsApp al +57 319 660 0002, las 24 horas.