Autenticación

English version: Authentication.

Cada petición a la API se autentica con una clave API, enviada como token bearer:

GET /v1/me HTTP/1.1
Host: api.usa.dialerdigital.com
Authorization: Bearer dd_k3y…example-not-a-real-key

No hay un flujo de inicio de sesión aparte, ni cookies de sesión, ni baile de OAuth. La clave es tu cuenta: acota cada petición a tus datos y a nada más (lo impone la seguridad a nivel de fila de la base de datos, no un código de aplicación en el que tengas que confiar).

Las claves se guardan con hash

Dialer Digital guarda solo el SHA-256 de tu clave. Nadie — tampoco nosotros — puede leer una clave de vuelta desde la base de datos. Si pierdes una clave, la rotas; nunca la «recuperas».

Obtener tu clave

Tu primera clave la emite el equipo de Dialer Digital durante la incorporación. A partir de entonces gestionas las claves tú mismo mediante la API (o el dashboard, que usa la misma clave).

Gestionar claves

Método	Ruta	Qué hace
GET	/v1/api_keys	Lista las claves: id, etiqueta, created_at, revoked_at. Nunca el material de la clave.
POST	/v1/api_keys	Crea una clave. El token en claro se devuelve una sola vez — guárdalo de inmediato.
DELETE	/v1/api_keys/{id}	Revoca. Es inmediato; la fila se conserva para tu pista de auditoría.

Emitir y revocar exigen un inicio de sesión account_admin del dashboard; en cuanto la cuenta tiene un account_admin activo, una clave dd_ recibe también 403 role_forbidden ahí (y al invitar o deshabilitar personas). Detalles y salida: guía de la API REST.

Formas completas de petición y respuesta: referencia de claves API.

Crear una clave

curl -s -X POST $API/v1/api_keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "warehouse-etl"}'

{
  "api_key": {
    "id": "7c0e6a1e-3f2b-4d5c-9e8f-1a2b3c4d5e6f",
    "label": "warehouse-etl",
    "revoked_at": null,
    "created_at": "2026-07-01T14:30:00Z"
  },
  "token": "dd_k3y…shown-exactly-once…"
}

Rotación sin tiempo de inactividad

1. POST /v1/api_keys con una etiqueta nueva — recibes el nuevo token en claro.
2. Despliega el nuevo token en tu integración y confirma que funciona (GET /v1/me).
3. DELETE /v1/api_keys/{old-id} — la clave antigua deja de funcionar de inmediato, en todas partes. La revocación también cierra las conexiones WebSocket vivas en un latido (heartbeat).

Como puedes tener varias claves activas, la rotación nunca exige una ventana de mantenimiento.

Cuando la autenticación falla

Estado	error.code	Significado	Qué hacer
401	unauthorized	Clave ausente, mal formada, desconocida o revocada.	Revisa la cabecera Authorization: Bearer; crea o rota la clave si fue revocada.
403	forbidden	La clave es válida pero la cuenta está suspendida.	Contacta a tu gerente de cuenta — ninguna petición tendrá éxito hasta que la cuenta se reactive.

Un 401 nunca dice cuál de esas condiciones se dio — es deliberado.

Buenas prácticas

• Una clave por integración, con etiqueta ("crm-sync", "warehouse-etl", …), para que la revocación sea quirúrgica.
• Solo en el servidor. Nunca incluyas una clave en apps móviles, navegadores ni configuración visible al cliente.
• Rota según tu calendario normal de credenciales, y de inmediato ante la salida de una persona del equipo o una sospecha de exposición.
• Registra el X-Request-ID de las llamadas fallidas — soporte puede rastrear cualquier petición a partir de él.