Autenticación

Copera CLI te autentica una vez y luego ejecuta cada comando como tú. Esta página cubre los tipos de token, los flujos de inicio de sesión, los perfiles y cómo la CLI decide qué credencial usar cuando hay varias disponibles.

Tipos de token

Copera emite dos tipos de tokens:

• Personal Access Token (cp_pat_...): vinculado a tu cuenta de usuario. Cubre toda la superficie de la CLI y es obligatorio para los comandos de docs, drive, notificaciones, búsqueda y workspace. En caso de duda, usa un PAT.
• Integration API Key (cp_key_...): vinculada a una integración en lugar de a un usuario. Funciona solo para boards y channels.

consejo

Las operaciones de docs y drive siempre requieren un Personal Access Token con los permisos de workspace adecuados. Si ves un error de autenticación en copera docs ... o copera drive ..., verifica que estés usando un token cp_pat_....

Superficie	cp_pat_ (Personal Access Token)	cp_key_ (Integration API Key)
Boards / tablas / filas	Sí	Sí
Channels	Sí	Sí
Docs	Sí	No
Drive	Sí	No
Workspace / búsqueda / notificaciones	Sí	No

Flujos de inicio de sesión

La forma más rápida de autenticarse es el flujo guiado por navegador:

copera auth login

La CLI imprime una URL de Copera, la abre en tu navegador predeterminado cuando es posible y te pide que pegues el token generado de vuelta en la terminal. La URL impresa siempre está disponible, por lo que el mismo flujo funciona por SSH, en WSL o en cualquier terminal donde el navegador no se abra automáticamente.

Si ya tienes un token, puedes guardarlo directamente:

Comando	Cuándo usarlo
copera auth login	Quieres el flujo guiado por navegador.
copera auth login --token=<value>	Ya tienes un token y quieres guardarlo directamente, sin abrir un navegador.
copera auth login --token	Ya tienes un token y quieres un aviso de pegado enmascarado: sin navegador, y el token nunca queda en el historial de tu shell.

Una vez que has iniciado sesión, tu token se almacena en ~/.copera.toml y se reutiliza en cada comando posterior.

Usar un token sin iniciar sesión

Para CI, scripts y agentes de IA, prefiere una variable de entorno: anula todo archivo de configuración y nunca persiste en disco:

export COPERA_CLI_AUTH_TOKEN="cp_pat_xxx"

En Windows PowerShell:

$env:COPERA_CLI_AUTH_TOKEN = "cp_pat_xxx"

También puedes pasar un token por comando con --token, que supera a todo archivo de configuración pero tiene menor prioridad que la variable de entorno:

copera boards list --token cp_pat_xxx

Inspeccionar la sesión actual

copera auth status     # perfil activo + de dónde vino el token
copera auth whoami     # a quién pertenece el token

copera auth status es especialmente útil cuando algo se comporta de forma inesperada: informa si la CLI tomó un token de tu entorno, de un archivo de configuración del proyecto o de tu directorio home:

{
  "profile": "default",
  "token_source": "environment variable COPERA_CLI_AUTH_TOKEN",
  "token": "cp_***...***xY2z",
  "configured": true
}

Cerrar sesión

copera auth logout

Esto elimina la credencial almacenada. Ejecuta copera auth login de nuevo en cualquier momento.

Orden de resolución del token

Cuando ejecutas un comando, la CLI busca un token en este orden: gana el primero que encuentre:

Prioridad	Origen	Ejemplo
1	Variable de entorno	COPERA_CLI_AUTH_TOKEN=cp_pat_xxx
2	Flag --token en el comando	copera boards list --token cp_pat_xxx
3	.copera.local.toml en el directorio actual	Token local del proyecto, ignorado por git
4	.copera.toml en el directorio actual	Valores predeterminados compartidos del proyecto
5	~/.copera.toml	Respaldo a nivel de usuario

Esto es intencional:

• CI y agentes pueden anular todo lo demás estableciendo COPERA_CLI_AUTH_TOKEN.
• Los tokens por proyecto viven en .copera.local.toml, que debería agregarse a .gitignore.
• Los valores predeterminados compartidos del proyecto (como un board_id y table_id predeterminados, sin token) viven en .copera.toml, que es seguro de confirmar.
• Tu token personal se ubica en ~/.copera.toml para todo lo demás.

Consulta Configuración para el formato completo del archivo de configuración y cómo encajan los perfiles.

Perfiles

Un perfil agrupa un token junto con IDs de recursos predeterminados para que dejes de repetir flags como --board y --table. Los perfiles viven en tus archivos de configuración bajo [profiles.<name>]:

[profiles.default]
token    = "cp_pat_abc123..."
board_id = "66abc123def456789012abcd"

[profiles.work]
token    = "cp_key_xyz789..."
board_id = "66ghi789jkl012345678mnop"
table_id = "66pqr012stu345678901vwxy"

Selecciona un perfil por comando o por shell. Si omites --profile, la CLI usa default (o el default_profile establecido en tu configuración):

copera boards list --profile work
COPERA_PROFILE=work copera boards list

Sandbox

Para apuntar al entorno de desarrollo de Copera en lugar de a producción, establece COPERA_SANDBOX=1. Esto cambia la URL base de la API a https://api-dev.copera.ai/public/v1 y apunta copera auth login a la aplicación web de desarrollo:

COPERA_SANDBOX=1 copera auth login
COPERA_SANDBOX=1 copera boards list

¿De dónde obtengo un token?

Genera un token desde la aplicación web de Copera:

1. Abre el workspace al que quieres acceder.
2. Ve a Settings → Personal Access Tokens (para cp_pat_...) o Settings → Integrations (para cp_key_...).
3. Crea un token, cópialo y pégalo en el aviso de la CLI o establécelo como COPERA_CLI_AUTH_TOKEN.

Para más información sobre lo que puede hacer cada tipo de token, consulta la guía de Autenticación de la API.