# Autenticación y Acceso para Agentes de IA en Clipvie

> Este documento describe cómo los agentes autónomos (Claude, Cursor, ChatGPT, AutoGPT, agentes basados en LLM) deben autenticarse para utilizar la API y el servidor MCP de Clipvie.

- **Dominio principal**: https://clipvie.com
- **Endpoint API**: https://api.clipvie.com
- **Servidor MCP**: https://api.clipvie.com/mcp
- **Catálogo de Servicios**: https://clipvie.com/.well-known/api-catalog
- **Manifiesto LLMs**: https://clipvie.com/llms.txt

---

## 🔑 1. Tipo de Autenticación: API Key Bearer

Clipvie utiliza autenticación basada en claves de API transmitidas a través de la cabecera estándar `Authorization`:

```http
Authorization: Bearer ck_live_...
```

### ¿Cómo obtener una clave de API?
1. El usuario humano titular de la cuenta debe iniciar sesión en [clipvie.com](https://clipvie.com).
2. Dirigirse a **Ajustes** → **Acceso para agentes**.
3. Crear una nueva clave asignando los permisos (*scopes*) requeridos para el agente.
4. La clave comienza siempre por el prefijo `ck_live_`.

---

## 🛡️ 2. Permisos y Scopes Disponibles

Los permisos determinan qué operaciones puede ejecutar el agente en nombre del usuario:

| Scope | Tipo | Descripción |
|---|---|---|
| `projects:read` | Lectura | Consultar proyectos y estado de procesamiento. |
| `projects:write` | Escritura | Importar vídeos desde URLs (YouTube/Twitch) o crear proyectos. |
| `clips:read` | Lectura | Obtener clips candidatos, timestamps y transcripciones. |
| `clips:write` | Escritura | Aprobar clips, editar límites y solicitar exportación. |
| `publications:read` | Lectura | Consultar historial de publicaciones en redes sociales. |
| `account:read` | Lectura | Consultar plan contratado, minutos consumidos y cuota restante. |
| `ai:write` | Escritura | Solicitar scoring y generación de textos publicitarios vía IA. |
| `payments:write` | Facturación | Crear sesiones de compra o checkout de minutos adicionales. |

---

## 🤖 3. Uso con el Protocolo MCP (Model Context Protocol)

Para agentes que soportan MCP (como Claude Desktop, Cursor o cualquier cliente compatible):

```json
{
  "mcpServers": {
    "clipvie": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-fetch",
        "https://api.clipvie.com/mcp"
      ],
      "env": {
        "CLIPVIE_API_KEY": "ck_live_..."
      }
    }
  }
}
```

O vía llamada HTTP directa (Transporte Streamable HTTP sin sesión):

```http
POST /mcp HTTP/1.1
Host: api.clipvie.com
Authorization: Bearer ck_live_...
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}
```

---

## 🚫 4. Respuestas de Error y Códigos de Estado

- **`401 Unauthorized`**: Falta la cabecera `Authorization` o la clave proporcionada es inválida/revocada.
  ```json
  { "error": "API Key inválida o no proporcionada" }
  ```
- **`403 Forbidden`**: La clave de API es válida pero no tiene el *scope* necesario para la operación solicitada.
  ```json
  { "error": "Permisos insuficientes. Requiere scope: projects:write" }
  ```
- **`402 Payment Required`**: El usuario ha agotado los minutos de procesamiento de su plan o cuota mensual.
  ```json
  { "error": "Cuota de minutos agotada para el periodo actual" }
  ```
- **`429 Too Many Requests`**: Se ha superado el límite de llamadas por minuto (120 req/min por defecto).