Autenticación

graph8 ofrece tres métodos de autenticación según el tipo de integración:

Método	Caso de uso	Dónde obtenerlo
API Key	REST API, CLI (servidor), funcionalidades SDK del servidor	Configuración > MCP & API > pestaña API
Write Key	SDK del lado del cliente (seguimiento, ID de visitante, formularios, widgets)	Configuración > MCP & API > fragmento de seguimiento
OAuth	MCP Server (Claude.ai, Claude Desktop, Cursor)	Automático: pegue la URL e inicie sesión

¿Qué clave necesita?

• ¿Desarrolla una aplicación web? Use el SDK de JavaScript con una write key (g8.init({ writeKey }))
• ¿Desarrolla un servidor o script? Use la REST API o el CLI con una API key
• ¿Usa un agente de IA? Use el MCP Server con OAuth (no requiere clave)

La API para desarrolladores autentica las solicitudes mediante claves API de organización. No se aceptan tokens JWT: utilice una API key para todo acceso programático.

Creación de una API Key

1. Vaya a Configuración -> API en su espacio de trabajo de graph8
2. Haga clic en Crear API Key
3. Ingrese un nombre (por ejemplo, “CRM Sync” o “Exportación de datos”)
4. Opcionalmente, defina una fecha de vencimiento (1 a 365 días)
5. Copie la clave de inmediato: solo se muestra una vez

Consejo

Almacene su API key en una variable de entorno o en un gestor de secretos. No podrá recuperarla una vez que cierre el diálogo de creación.

Uso de su API Key

Incluya la clave en el encabezado Authorization con el prefijo Bearer:

cURL

export API_KEY="your_api_key_here"

curl "https://be.graph8.com/api/v1/contacts" \
  -H "Authorization: Bearer $API_KEY"

Python

import requests

API_KEY = "your_api_key_here"
BASE_URL = "https://be.graph8.com/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

response = requests.get(f"{BASE_URL}/contacts", headers=HEADERS)
print(response.json())

TypeScript

const API_KEY = "your_api_key_here";
const BASE_URL = "https://be.graph8.com/api/v1";

const response = await fetch(`${BASE_URL}/contacts`, {
  headers: { Authorization: `Bearer ${API_KEY}` }
});

const data = await response.json();
console.log(data);

Características de la clave

Propiedad	Detalles
Alcance	Nivel de organización: acceso a todos los datos de su organización
Formato	Token opaco (no es un JWT)
Vencimiento	Opcional, de 1 a 365 días desde la creación
Rotación	Elimine y cree una nueva clave, o use el botón Rotar en Configuración
Límite de solicitudes	5 solicitudes/segundo (por organización): consulte Límites de solicitudes

Nota

Las API keys heredan automáticamente el alcance de la organización: no se requiere el encabezado X-Org-Id.

Errores de autenticación

Estado	Significado	Solución
401	Encabezado Authorization ausente o inválido	Verifique que su API key sea correcta
401	Se proporcionó un token JWT en lugar de una API key	Use una API key de organización, no un token de sesión del navegador
401	La API key no está asociada a una organización	Asegúrese de que la clave se haya creado en Configuración -> API
429	Límite de solicitudes superado	Espere y reintente con retroceso exponencial (consulte Límites de solicitudes)

Ejemplo de respuesta de error

{
  "detail": "Missing Authorization header. Use: Authorization: Bearer <api_key>"
}

Buenas prácticas de seguridad

Haga:

• Almacene las claves en variables de entorno o en un gestor de secretos
• Use claves separadas para desarrollo y producción
• Defina fechas de vencimiento en las claves
• Rote las claves de forma periódica
• Elimine sin demora las claves que ya no utilice

No haga:

• Subir claves al control de versiones
• Compartir claves por correo electrónico o chat
• Exponer claves en JavaScript del frontend o en código del lado del cliente
• Registrar claves en la salida de la aplicación

Precaución

Si sospecha que una clave se ha visto comprometida, elimínela de inmediato en Configuración -> API y cree una nueva.