Autenticación

La API de Platica utiliza autenticación Bearer. El header Authorization acepta dos credenciales:

Credencial	Prefijo	Para qué
API Key	`pl_key_`	Integraciones REST, scripts, CI, Postman. Acceso completo al workspace de la key.
OAuth (MCP)	`pl_at_`	Access token que emite Platica cuando conectas un cliente MCP. Carga tu usuario, tus workspaces autorizados, tus scopes y tu rol.

Authorization: Bearer pl_key_xxxxxxxxxxxxx
Authorization: Bearer pl_at_xxxxxxxxxxxxx

Para conectar Cursor, Claude o VS Code no generes una key: pega https://api.platica.mx/mcp y autoriza. La guía completa está en Autenticación MCP . El resto de esta página cubre la API Key, que sigue siendo el camino para curl y la REST API.

Formato del header

Authorization: Bearer pl_key_xxxxxxxxxxxxx

Un token OAuth de MCP usa el mismo header con el prefijo pl_at_.

Obtener tu API Key

Puedes generar tu API Key directamente desde el dashboard de Platica, sin necesidad de contactar al equipo de soporte.

Abre la configuración — Desde el dashboard de Platica, dirígete a Configuración y selecciona la sección API Keys.
Crea una nueva API Key — Haz clic en Crear nueva API Key e ingresa un nombre descriptivo para identificarla.
Guarda tu API Key — La API Key se mostrará una única vez. Cópiala y guárdala en un lugar seguro; no podrás verla de nuevo.
Configura tus peticiones — Incluye la API Key en el header de todas tus peticiones a la API.

Ejemplo de petición autenticada

curl -X GET "https://api.platica.mx/v1/agents" \
  -H "Authorization: Bearer pl_key_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Consideraciones importantes

Advertencia

Mantén tu API Key segura. No la expongas en código público, repositorios o aplicaciones del lado del cliente. Si sospechas que ha sido comprometida, contacta inmediatamente a integraciones@platica.mx .

Tu API Key tiene acceso únicamente al workspace desde el que fue creada. Esto significa que:

Solo puedes gestionar agentes, clientes y conversaciones dentro de ese workspace.
No tendrá acceso a otros workspaces, aunque tu cuenta forme parte de ellos.
Si necesitas acceder a varios workspaces vía API, deberás generar una API Key en cada uno.

Errores de autenticación

Si tu API Key es inválida o no está presente, recibirás un error 401 Unauthorized:

{
  "code": 401,
  "error": "Unauthorized",
  "details": "Invalid or missing API key"
}

Con un token OAuth (pl_at_…) el 401 incluye un header WWW-Authenticate que apunta al discovery (RFC 9728). Un 403 por falta de platica:write usa el challenge insufficient_scope para que el cliente pida un step-up. Detalle en Autenticación MCP y Errores .

Si la credencial cubre varios workspaces, las escrituras exigen ?workspace=<id>. GET /v1/workspaces lista los IDs que esa credencial puede usar.

Anterior Bienvenida a la API Siguiente Workspaces