Inicio de Sesión por Enlace (SSO)

CapData ofrece dos endpoints de Single Sign-On (SSO) para iniciar sesión en el portal web mediante un enlace. Estos endpoints no son para consumo de API programática; están pensados para acceso interactivo de usuarios (por ejemplo, abrir el panel desde tu propio sistema con un clic).

Seguridad: El parámetro key contiene tu credencial (API Key o Token de Agente). Trátalo como una contraseña. No lo expongas en HTML público ni en frontend; preferiblemente realiza un redirect 302 desde tu backend para mantener la clave oculta.

Endpoints disponibles

GET /auth/apikey-login?key=API_KEY

Inicia sesión como Cliente (Propietario) o Agencia utilizando la API Key de esa cuenta. Si la cuenta está activa, se crea la sesión y se redirige automáticamente a la primera sección accesible (dashboard, calendario, chat IA, etc.) según permisos.

Parámetros

key (obligatorio): API Key del Propietario o de la Agencia.

Ejemplo (enlace directo)

URL

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

Comportamiento

Método: GET
Respuesta típica: 302 Found → redirección al panel correspondiente.
En caso de clave inválida o cuenta inactiva: redirección a login con un mensaje informativo.
No consume tokens.

GET /auth/agent-apikey-login?key=AGENT_TOKEN

Inicia sesión como Agente (EmployeeToken) usando su token de agente. La sesión se asocia al cliente (Propietario o Agencia) al que pertenece el agente y se redirige al panel del agente.

Parámetros

key (obligatorio): Token del Agente (EmployeeToken).

Ejemplo (enlace directo)

URL

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

Comportamiento

Método: GET
Respuesta típica: 302 Found → redirección al panel del agente.
Requisitos: el agente debe estar activo y la cuenta principal asociada también.
No consume tokens.

Uso recomendado (mantener la clave oculta)

Para no exponer la API Key o el Token en el HTML del navegador, realiza el SSO desde tu backend: tu servidor construye la URL de SSO con la clave almacenada en servidor y hace un redirect 302 al usuario.

Ejemplo en Node/Express

JavaScript (Node/Express)

app.get("/abrir-capdata", (req, res) => {
  // La API Key se lee desde variables de entorno o un almacén seguro del backend
  const API_KEY = process.env.CAPDATA_API_KEY;
  const url = `https://capdata.es/auth/apikey-login?key=${encodeURIComponent(API_KEY)}`;
  return res.redirect(302, url);
});

Ejemplo en Python/Flask

Python (Flask)

import os
from flask import Flask, redirect

app = Flask(__name__)

@app.get("/abrir-capdata")
def abrir_capdata():
    api_key = os.environ["CAPDATA_API_KEY"]
    url = f"https://capdata.es/auth/apikey-login?key={api_key}"
    return redirect(url, code=302)

Tip: Si quieres ofrecer “un solo clic” desde emails o tu app, apunta esos enlaces a una ruta de tu backend (como /abrir-capdata) y allí haces el redirect con la clave almacenada en servidor. Así la credencial nunca aparece en el HTML del cliente.

Buenas prácticas y seguridad

Trata la clave como una contraseña: no la incluyas en frontend, ni en repos públicos.
Usa redirects desde backend: evita enlaces directos con la clave en emails o páginas.
Revocación/rotación: si sospechas exposición, desactiva/rota la API Key o el Token del Agente desde el portal.
Ámbito del acceso: el SSO otorga acceso a todo lo que permite esa cuenta; revisa los permisos antes de compartir enlaces.
HTTPS siempre: usa solo URLs https para prevenir fugas por tráfico en claro.

FAQ

¿Caduca el enlace de SSO?

No hay caducidad automática: el enlace funciona mientras la API Key (o Token de Agente) sea válido y la cuenta esté activa. Si rotas o desactivas la credencial, los enlaces existentes dejarán de funcionar.

¿Consume tokens iniciar sesión por SSO?

No. El SSO solo establece la sesión web. Los tokens se consumen al usar servicios como Chat IA, extracción o transcripción.

¿Puedo limitar el alcance (scopes) del SSO?

No. El acceso reflejará los permisos nativos de la cuenta o agente que autenticas.

¿Es válido para APIs?

No. Para invocar APIs usa las cabeceras de autenticación (por ejemplo, X-CapData-Token). El SSO es exclusivamente para iniciar sesión en el portal web.