Tokens de API — Cloady Docs

Un token de API, también llamado clave de API, permite que un script, un job de CI, la CLI, un SDK, Terraform o un agente de IA actúe en tu nombre en Cloady. Cada solicitud que hace se ejecuta con tu cuenta, en los espacios de trabajo a los que perteneces y con el rol que tienes en cada uno, limitada por el alcance del token.

Un token tiene este aspecto: cldy_ seguido de 48 caracteres hexadecimales.

cldy_3f9a1c07d2b84e65a0c9e1f4b7d2a8c6e05f19b3a7d4c2e8

Crear un token en el panel

Haz clic en tu avatar de cuenta, en la esquina superior derecha, y luego en Account settings.
Abre la pestaña API tokens y haz clic en + New token.
Ponle al token un nombre que diga dónde se va a usar, como GitHub Actions o CLI · laptop. Más adelante verás el nombre en la lista.
Elige un alcance: Read only, Deploy only o Full access. Consulta Alcances para ver qué permite cada uno.
Elige una caducidad: No expiry, 30 days, 90 days o 1 year.
Haz clic en Create token.
Copia el token enseguida. Cloady lo muestra una sola vez y solo guarda un hash de él, así que no se puede volver a mostrar. Si lo pierdes, revócalo y crea uno nuevo.

Guarda el token en un lugar seguro, como el almacén de secretos de tu proveedor de CI o un gestor de contraseñas. Nunca lo pegues en un ticket de soporte, en un chat ni en un repositorio público.

Alcances

Cada token tiene un único alcance. El alcance fija el rol más alto del espacio de trabajo con el que puede actuar el token; además, se sigue aplicando el rol que tú tienes en cada espacio de trabajo.

Alcance	Etiqueta en el panel	Rol máximo	Qué permite
`read`	Read only	viewer	Listar e inspeccionar espacios de trabajo, aplicaciones, despliegues y logs. Sin cambios.
`deploy`	Deploy only	developer	Todo lo que permite `read`, más desplegar, redesplegar, iniciar, detener y reiniciar apps, gestionar dominios y variables, y eliminar una aplicación.
`full`	Full access	owner	Todo, incluidos crear espacios de trabajo, los ajustes del espacio de trabajo, los miembros, las integraciones, la facturación y crear más tokens.

Elige el alcance más reducido que cumpla su función:

Un pipeline de CI o un agente de IA de programación que despliega: Deploy only.
Un panel de métricas, un monitor o un informe que solo lee: Read only.
Terraform que crea espacios de trabajo, o cualquier cosa que cambie la facturación: Full access.

Una solicitud que necesita más de lo que permite el alcance del token recibe 403 forbidden, aunque tu propio rol en el espacio de trabajo sea más alto.

Usar el token

API HTTP

Envía el token como token bearer en cada solicitud a https://cloady.com/api:

Terminal

curl https://cloady.com/api/workspaces \
  -H "Authorization: Bearer cldy_…"

CLI

Terminal

cloady login cldy_…

La CLI guarda el token en ~/.config/cloady/config.json. También lee CLOADY_TOKEN del entorno, lo que viene bien para los jobs de CI, y acepta --token cldy_… en cualquier comando. Consulta la guía de la CLI.

SDK

TypeScript

import { createCloady } from "@cloady/sdk";

const cloady = createCloady({ auth: process.env.CLOADY_TOKEN });

from cloady import Cloady

cloady = Cloady(base_url="https://cloady.com", token="cldy_…")

Terraform

El proveedor lee CLOADY_TOKEN, o un argumento token en el bloque del proveedor. Consulta la guía de Terraform.

Terminal

export CLOADY_TOKEN=cldy_…

MCP

El servidor @cloady/mcp lee el token de BEARER_TOKEN_CLOADY:

Terminal

claude mcp add cloady -e BEARER_TOKEN_CLOADY=cldy_… -- npx -y @cloady/mcp

Los clientes que se conectan al servidor alojado en https://cloady.com/api/mcp inician sesión a través de tu navegador, y Cloady crea el token por ellos. Consulta la guía de MCP.

Tokens que Cloady crea por ti

Algunos inicios de sesión crean un token en tu nombre, y esos tokens aparecen en la misma lista:

cloady login sin token inicia sesión a través de tu navegador y crea un token llamado Cloady CLI.
Conectar a Cloady un cliente MCP o una app de IA como Claude o ChatGPT crea un token con el nombre de ese cliente y con el alcance que elijas en la página de consentimiento.

Revocar uno de estos tokens cierra la sesión de esa herramienta.

Crear un token por la API

Un token con Full access, o una sesión iniciada en el navegador, puede crear otro token:

Terminal

curl https://cloady.com/api/me/tokens \
  -H "Authorization: Bearer cldy_…" \
  -H "Content-Type: application/json" \
  -d '{"name": "GitHub Actions", "scope": "deploy", "expires": "90d"}'

Campo	Valores	Predeterminado
`name`	De 1 a 80 caracteres	obligatorio
`scope`	`read`, `deploy`, `full`	`full`
`expires`	`never`, `30d`, `90d`, `1y`	`never`

La respuesta incluye los datos del nuevo token y, solo esta vez, su valor en secret:

JSON

{
  "token": {
    "id": "…",
    "name": "GitHub Actions",
    "scope": "deploy",
    "prefix": "cldy_3f9a1c0",
    "workspaceId": null,
    "lastUsedAt": null,
    "expiresAt": "2027-02-01T12:00:00.000Z",
    "createdAt": "2026-11-03T12:00:00.000Z"
  },
  "secret": "cldy_…"
}

Consulta createToken, listTokens y revokeToken para ver la referencia completa.

Ver y revocar tokens

Account settings → API tokens lista todos los tokens activos con su nombre, su alcance, los primeros 12 caracteres de su valor (cldy_3f9a1c0), cuándo se usó por última vez y cuándo caduca. Haz clic en Revoke para desactivar un token; deja de funcionar al instante.

Por la API, GET /api/me/tokens lista tus tokens y DELETE /api/me/tokens/{id} revoca uno.

Revoca un token cuando la persona, el equipo o el servicio que lo usa ya no lo necesite, y de inmediato si podría haberse filtrado. Después, crea uno nuevo.

Errores

Estado	Código	Significado
`401`	`unauthorized`	Falta el token, está mal formado, ha caducado o se ha revocado.
`403`	`forbidden`	El alcance del token, o tu rol en el espacio de trabajo, no permite la solicitud.
`404`	`not_found`	No eres miembro de ese espacio de trabajo, o el recurso no existe.

Para ver cómo se combinan los alcances y los roles del espacio de trabajo en cada solicitud, consulta el resumen de la API.

En esta página