Autenticación
La API pública se autentica con una API key de tu cuenta. No hay usuario ni contraseña, ni tokens que se renuevan: una clave vale hasta que la revoques.
Authorization: Bearer alttos_sk_...Toda llamada lleva ese header. Sin él, o con una clave que no reconocemos, la respuesta es 401 invalid_api_key.
Crear una clave
Entra a Configuración → API
La pestaña API de Configuración es solo para administradores. Un miembro del equipo no la ve ni puede llegar a ella por URL directa.
Ponle un nombre que te sirva a ti
El nombre solo lo ves tú y existe para un momento puntual: el día que tengas que revocar una clave, quieres saber cuál corresponde a qué integración. “Sistema de citas” es mejor nombre que “clave 2”.
Elige los permisos
Marca únicamente lo que la integración necesita (ver la tabla de abajo). Una clave sin permisos no es válida: al menos uno es obligatorio.
Copia la clave ahora
La clave completa se muestra una sola vez, en el momento de crearla. No la guardamos en claro: en nuestra base de datos vive solo su huella criptográfica, así que ni nosotros podemos recuperarla después. Si la pierdes, revocas esa clave y creas otra.
Guarda la clave donde guardas tus otros secretos (variables de entorno del servidor, un gestor de secretos). Nunca la pongas en el código de tu frontend, en un repositorio ni en una app móvil: quien la tenga puede enviar mensajes en nombre de tu negocio, y esos mensajes te los cobra Meta a ti.
Formato de la clave
Una clave se ve así:
alttos_sk_7Qw3nR8kZ2xLp0VbTy6MaHdJ4Fc9SgE1uNvXoI5rBjKEmpieza siempre por alttos_sk_, seguido de 43 caracteres aleatorios. En el panel solo verás los primeros 16 (alttos_sk_7Qw3nR…), que sirven para identificarla en la lista sin exponer el secreto.
Permisos (scopes)
Cada clave lleva su lista de permisos y cada operación exige el suyo. Si una clave no lo tiene, la respuesta es 403 missing_scope con el permiso que falta en detail.required_scope.
| Permiso | Habilita |
|---|---|
messages:send | POST /v1/messages |
messages:read | GET /v1/messages/{id} |
channels:read | GET /v1/channels |
contacts:read | GET /v1/contacts y GET /v1/contacts/{id} |
El criterio es sencillo: da solo lo que la integración usa. Un sistema que únicamente dispara avisos necesita messages:send y messages:read, y no tiene por qué poder leer tu base de contactos.
Una API key nunca puede crear ni revocar claves, ni acceder a la gestión de tu cuenta. Eso solo lo hace un administrador desde el panel. Si una clave se filtra, el daño está acotado a sus permisos.
Rotar una clave sin cortar el servicio
Puedes tener varias claves activas a la vez, y ese es justamente el mecanismo para rotar sin ventana de caída:
Crea la clave nueva
Con los mismos permisos que la que vas a reemplazar.
Despliega tu integración con la clave nueva
Las dos claves funcionan en paralelo mientras dure el despliegue.
Verifica que la nueva se está usando
En la lista de claves, la columna Último uso se actualiza cuando la clave hace llamadas (con un retardo de hasta un minuto, para no escribir en cada petición).
Revoca la vieja
En cuanto la vieja deje de registrar uso, revócala.
Revocar es inmediato e irreversible. A partir de ese momento, cualquier llamada con esa clave responde 401 invalid_api_key. No hay forma de reactivarla: si te equivocaste, crea otra.
Vencimiento
Al crear una clave eliges si vence: no vence (el default) o a los 30, 60, 90 o 365 días.
El default es deliberado. Una clave de API vive en tu servidor y su trabajo es correr desatendida durante años; si venciera sola por defecto, tendrías una caída programada en el calendario sin haberla pedido. Cuando vence, toda llamada que la use responde 401 invalid_api_key, igual que si la hubieras revocado.
Donde el vencimiento sí vale la pena es en claves que le das a un tercero —un proveedor, una consultora, una prueba de concepto—: en vez de confiar en que alguien se acuerde de revocarla cuando el trabajo termine, se apaga sola.
Si eliges un vencimiento, te avisamos por correo una semana antes y otra vez el día anterior, para que puedas rotarla sin apuro (crea la nueva, despliega, revoca la vieja — ver arriba). En el panel, la lista de claves muestra cuántos días le quedan a cada una.
Ver qué está haciendo cada clave
En la misma pestaña API del panel, debajo de la lista de claves, está Actividad reciente: las últimas llamadas que la API pública recibió de tu cuenta, con la clave que las hizo, el método y la ruta, el código de respuesta, el código de error cuando lo hubo, la latencia y el request_id.
Puedes filtrar por clave y por resultado (correctas, error del cliente, error del servidor). Es el primer lugar donde mirar cuando una integración no está funcionando: casi siempre el código de error te dice exactamente qué corregir sin que tengas que abrir un ticket.
Solo se guarda esa metadata. El contenido de tus mensajes nunca queda en ese registro. Las filas se conservan 30 días.
Errores de autenticación
| Código | Estado | Qué pasó y qué hacer |
|---|---|---|
invalid_api_key | 401 | Falta el header, está mal formado, o la clave no existe, fue revocada o venció. Es el mismo error para todos esos casos a propósito, para no revelar qué claves existen. Verifica que mandas Authorization: Bearer y que la clave sigue activa en el panel. |
feature_not_in_plan | 403 | La clave es válida, pero tu plan no incluye la API pública. Cambia a Growth o Business desde Facturación. |
missing_scope | 403 | La clave es válida pero no tiene el permiso que esa operación exige. detail.required_scope te dice cuál. Los permisos no se editan: crea una clave nueva con los permisos correctos y reemplaza la anterior. |
{
"error": {
"code": "missing_scope",
"message": "Esta operación requiere el scope contacts:read.",
"detail": { "required_scope": "contacts:read" },
"request_id": "req_7ea02989331d065d"
}
}