Autenticación en la API de CapData

Todas las peticiones a las APIs de CapData deben ser autenticadas. Utilizamos un sistema de tokens basado en cabeceras HTTP para garantizar que solo los usuarios autorizados puedan acceder a los recursos.

Cómo Obtener tu API Key Principal

Tu API Key principal es la credencial fundamental para interactuar con los servicios. Cada cuenta (Propietario o Agencia independiente) tiene una única API Key.

1. Inicia sesión en tu Portal CapData.
2. En el panel principal (Dashboard), verás una sección llamada "Tu Clave API Principal".
3. Copia esta clave. Este es el valor que debes usar en la cabecera X-API-Key o X-CapData-Token según el endpoint.

Tipos de Tokens y Cabeceras

Dependiendo del endpoint y del actor que realiza la acción, deberás usar una cabecera de autenticación específica.

X-API-Key (API General)

Utilizada por la API General (/api/extract, /api/update_reservation). El valor puede ser la API Key de un Propietario o una Agencia.

X-API-Key: tu_api_key_de_propietario_o_agencia

X-Employee-Token (API General para Agentes)

Utilizada por la API General cuando la acción es realizada por un Agente. Este token se crea en el portal, en la sección "Gestionar Mis Agentes".

X-Employee-Token: el_token_especifico_del_agente

X-Owner-API-Key (API de Gestión)

Utilizada exclusivamente por la API de Gestión (/api/management/*). El valor DEBE ser la API Key de un cliente con rol de Propietario.

X-Owner-API-Key: tu_api_key_de_propietario

X-CapData-Token (APIs Modernas)

Es la cabecera unificada y recomendada para las APIs más recientes, como la API de Chat y la API de Transcripción. El valor puede ser la API Key de un Propietario, una Agencia o el token de un Agente. El sistema identificará automáticamente el tipo de actor.

X-CapData-Token: tu_api_key_o_token_de_agente

SSO / Inicio de sesión por enlace

Además de las cabeceras de autenticación, CapData ofrece SSO por enlace para abrir el portal ya autenticado desde tus propios sistemas (deep-linking). Consulta la guía completa en la página de SSO.

Endpoints de SSO (solo lectura, ver guía)

• GET /auth/apikey-login?key=<API_KEY_CLIENTE_O_AGENCIA>
• GET /auth/agent-apikey-login?key=<TOKEN_DE_AGENTE>

https://capdata.es/auth/apikey-login?key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Buenas prácticas para usar enlaces SSO

• Usa siempre HTTPS y evita compartir los enlaces SSO en correos o chats públicos.
• No expongas claves en el frontend: si necesitas un enlace “click-to-login”, genera un redirect seguro en tu servidor que resuelva internamente la API Key (no la pongas en la URL pública).
• Rotación y revocación: rota periódicamente las API Keys y revoca cualquier clave comprometida.
• Restricción de uso: limita quién/desde dónde puede invocar estos enlaces (IP allowlist, firewalls, etc.).
• Caducidad y nonce (opcional): si implementas un wrapper propio, añade expiración y un identificador único por enlace para mitigar reusos no deseados.