Autenticación

Cada solicitud a la Public API debe incluir un token en el encabezado Authorization usando el esquema Bearer:

Authorization: Bearer <token>

Copera acepta tres tipos de token. El prefijo te indica (y le indica a la API) cuál estás usando.

Tipo de token	Prefijo	Identidad	Superficie
Personal Access Token	cp_pat_	Tú (el usuario que lo creó)	API completa
Integration API Key	cp_key_	La integración (un bot)	Solo Boards + Channels
Token OAuth de MCP	cp_oat_	El usuario conectado	Emitido por el servidor MCP

Personal Access Token (cp_pat_)

Un Personal Access Token autentica la API como tú. Las solicitudes se atribuyen a tu cuenta de usuario y heredan tu acceso dentro del Workspace, limitado por los scopes que le otorgues al token. Los PAT desbloquean la superficie completa de la API — boards, export, docs, drive, search, channels, notifications, workspace y bookings — y son la opción recomendada para scripts, pipelines de CI y automatización personal.

Cómo obtener uno

1. Abre Workspace Settings → Integrations.
2. Selecciona la pestaña Personal Tokens.
3. Haz clic en Create new token.
4. Asigna un nombre, elige los scopes que necesita y establece una fecha de expiración (hasta 1 año).
5. Copia el token de inmediato — solo se muestra una vez.

Características

• Acotado al Workspace — cada token está vinculado a un único Workspace.
• Actúa como tu identidad — las llamadas se atribuyen a ti y respetan tus permisos.
• Expira — hasta un máximo de 1 año; los tokens expirados devuelven 401.
• Con scopes — solo se respetan los scopes que otorgues.

Ejemplo

curl https://api.copera.ai/public/v1/docs/tree \
  -H "Authorization: Bearer cp_pat_your_token_here"

Integration API Key (cp_key_)

Una Integration API Key autentica como una integración (un bot) en lugar de como un usuario específico. Es la opción correcta cuando quieres una identidad separada que opere de forma independiente de cualquier usuario — por ejemplo, un bot que publica en channels o lee datos de boards.

nota

Las Integration API Keys cubren solo boards y channels. Para llamar a los endpoints de docs, drive, search, notifications, workspace o bookings, usa un Personal Access Token en su lugar.

Características

• Identidad de bot — las solicitudes se atribuyen a la integración, no a un usuario.
• Superficie de boards + channels — diseñada para los endpoints de board y channel.
• Requiere acceso explícito — a la integración se le deben otorgar los scopes correspondientes y agregarla como participante de los channels o boards específicos que necesita alcanzar.

Crea una integración y genera su key desde Workspace Settings → Integrations.

Token OAuth de MCP (cp_oat_)

Los tokens OAuth de MCP se emiten automáticamente cuando un cliente de IA se conecta a tu Workspace a través del servidor MCP. No los creas a mano — el flujo OAuth los genera en nombre del usuario. Autentican como el usuario que se conecta, acotados a lo que la integración de MCP tiene permitido hacer.

Si estás construyendo una integración directa, usa un PAT o una Integration API Key. Los tokens cp_oat_ son parte del flujo de conexión de MCP.

Scopes

Los scopes controlan a qué dominios puede acceder un token. Otorga solo lo que tu integración necesita.

Scope	Otorga acceso a
access_boards	Boards, tablas, filas, comentarios de filas, markdown de filas, exportación de tablas
access_channels	Channels, mensajes de channel, mensajes directos
access_docs	Documentos — lectura, escritura, búsqueda, árbol
access_drive	Drive — explorar, buscar, descargar, subir, carpetas
access_notifications	Notifications — listar, actualizar, eliminar
access_bookings	Bookings y tipos de booking

Notas sobre la cobertura de scopes:

• Los endpoints de Workspace (info, members, teams) requieren un PAT válido de un usuario interno (no externo) — no existe un scope de workspace separado.
• Search no tiene un único scope. Una solicitud de búsqueda devuelve únicamente los tipos de entidad que tu token tiene permitido leer: los documentos necesitan access_docs, los channels y mensajes necesitan access_channels, los elementos de drive necesitan access_drive. Otros tipos (como todos y chats de IA) se pueden buscar con cualquier token válido.
• Export se ejecuta sobre tablas de board, por lo que requiere access_boards.

Una solicitud a un dominio para el que tu token carece de scope devuelve 403 Forbidden. Consulta Manejo de errores.

Mejores prácticas de seguridad

• Almacena los tokens de forma segura — usa variables de entorno o un gestor de secretos. Nunca los incrustes directamente en el código.
• Nunca subas tokens al control de versiones — agrega los archivos de tokens a .gitignore; usa el almacén de secretos de tu CI/CD.
• Usa el scope mínimo — solicita únicamente los scopes que la integración necesita.
• Establece expiraciones cortas — elige el menor tiempo de vida práctico para los PAT.
• Rota con regularidad — reemplaza los tokens periódicamente y elimina los que no uses.
• Un token por uso — separa los tokens por integración o entorno para poder revocar de forma acotada.