# Autenticación

> Autentique las solicitudes de API con las claves de API de la organización

Source: https://docs.graph8.com/es/developers/authentication/

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 |

> **Tip: ¿Qué clave necesita?**
> - ¿Desarrolla una **aplicación web**? Use el [SDK de JavaScript](https://docs.graph8.com/developers/sdk/) con una **write key** (`g8.init({ writeKey })`)
> - ¿Desarrolla un **servidor o script**? Use la REST API o el [CLI](https://docs.graph8.com/developers/cli/) con una **API key**
> - ¿Usa un **agente de IA**? Use el [MCP Server](https://docs.graph8.com/developers/mcp/) 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

> **Tip:**
> 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**

```bash
export API_KEY="your_api_key_here"

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

**Python**

```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**

```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](https://docs.graph8.com/developers/rate-limits/) |

> **Note:**
> 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](https://docs.graph8.com/developers/rate-limits/)) |

### Ejemplo de respuesta de error

```json
{
  "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

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