Autenticación

La API REST de SIP Caller autentica las solicitudes con API Keys. Cada API Key tiene un token secreto, que tu aplicación envía en el encabezado Authorization de cada solicitud.

Crear una API Key

Las API Keys se crean desde la consola web, en Configuración > API Keys, por un usuario con el rol Administrador. Al crear la API Key, eliges:

• Un nombre, para identificar la aplicación que la usa.
• Una fecha de vencimiento. Después de esa fecha, la API Key deja de funcionar. El vencimiento no se puede extender más adelante.
• Los roles otorgados a la API Key, que definen lo que la aplicación puede hacer. Los roles no se pueden cambiar más adelante.

Cuando se crea la API Key, SIP Caller muestra su token una única vez. Cópialo y guárdalo en un lugar seguro, como un gestor de secretos. SIP Caller no almacena el token, por lo que no se puede recuperar: si lo pierdes, crea una nueva API Key.

Consulta API Keys para ver una guía paso a paso.

Autenticar las solicitudes

Envía el token como un token Bearer en el encabezado Authorization:

Authorization: Bearer API_KEY_TOKEN

Todas las solicitudes deben estar autenticadas. Ten en cuenta que:

• Una API Key pertenece a una única cuenta, por lo que el ACCOUNT_ID de la URL debe ser la cuenta donde se creó la API Key.
• Las solicitudes se deben realizar a través de HTTPS.
• El token es un secreto, y otorga acceso a tu cuenta. No lo incluyas en código del lado del cliente, como páginas web o aplicaciones móviles, y no lo subas a repositorios de código fuente.

Roles

Cada endpoint requiere que la API Key tenga al menos uno de los siguientes roles:

Rol	Permite
Administrador de Campañas	Acceso completo a campañas, números de campaña, listas negras, listas de contactos y reportes de campañas.
Lector de Campañas	Acceso de solo lectura a campañas, números de campaña, listas negras, listas de contactos y reportes de campañas.
Administrador de Números de Campaña	Leer, agregar y eliminar los números de las campañas. Se puede restringir a campañas específicas.
Proveedor de Números de Campaña	Agregar números a las campañas, sin poder leerlos ni eliminarlos. Se puede restringir a campañas específicas.

Otorga a cada aplicación solo los roles que necesita. Por ejemplo, un formulario web que envía nuevos leads a una campaña solo necesita el rol Proveedor de Números de Campaña, restringido a esa campaña.

Errores de autenticación

Estado	Cuándo
401 Unauthorized	Falta el encabezado Authorization, o el token tiene un formato incorrecto, no es válido o está vencido.
403 Forbidden	El token es válido, pero la API Key fue eliminada, pertenece a otra cuenta, o no tiene un rol que permita la operación.

Consulta Errores para ver el formato de las respuestas de error.

Revocar una API Key

Para revocar el acceso de una aplicación, elimina su API Key desde Configuración > API Keys. Las solicitudes realizadas con el token de una API Key eliminada fallan de inmediato con 403 Forbidden.

Recomendamos rotar las API Keys periódicamente: crea una nueva API Key, actualiza tu aplicación para que la use, y luego elimina la anterior.