Claves API, permisos, límites y paginación
Todas las operaciones públicas de /api/v1 requieren la cabecera Authorization: Bearer con la clave completa. Las claves nuevas usan el prefijo syn_ seguido de 40 caracteres hexadecimales.
Permisos
| Alcance | Operaciones |
|---|---|
| read | Consultas GET de recursos de la cuenta. |
| write | Las mismas consultas y POST /api/v1/contacts. |
La clave determina la cuenta consultada. Enviar el ID de otra cuenta no concede acceso a sus recursos. Genera claves diferentes para cada sistema y usa el menor alcance necesario.
Crear, guardar y revocar
Administra las claves en Desarrolladores. El secreto se entrega una sola vez al crear la clave; el panel conserva información identificativa para reconocerla. Si la pierdes, crea otra y sustituye la anterior en tu servidor. Después revoca la clave que ya no utilices.
Las rutas del panel para gestionar claves necesitan la sesión de usuario. No forman parte del contrato Bearer de /api/v1.
Límites por clave
| Plan | Solicitudes por ventana de 60 segundos |
|---|---|
| Starter | 60 |
| Pro | 120 |
| Business | 600 |
Las respuestas que superan el límite usan 429 y retry-after en segundos. Espera ese tiempo antes de volver a consultar. Los encabezados x-ratelimit-limit, x-ratelimit-remaining y x-ratelimit-reset informan del límite, remanente y fecha ISO de reinicio reportada. Los rechazos de autenticación pueden no incluir esos encabezados.
Paginación de listados
Los listados aceptan limit, entre 1 y 200, con 50 como valor predeterminado, y cursor. Usa el next_cursor de una respuesta como cursor de la siguiente, conservando los mismos filtros. Termina cuando sea null.
Los detalles /{id} y /_meta no son listados y no usan este sobre:
{
"data": [],
"next_cursor": null
}
Consistencia al leer mensajes
El listado de mensajes ordena por created_at e id, mientras el cursor filtra por id. Si necesitas una exportación histórica estrictamente completa, esta combinación no ofrece una garantía de recorrido cronológico sin saltos. Consulta al equipo antes de usarla como mecanismo de auditoría exhaustiva.
Correlación de errores
Registra x-request-id y el estado HTTP. Evita registrar Authorization. En Errores de API tienes las comprobaciones para cada código.