Cada petición a la API y al servidor MCP necesita una clave de API. Una clave pertenece a un espacio de trabajo, actúa como el propietario o administrador que la creó y solo puede llegar a los endpoints que permiten sus permisos. Las claves tienen la forma gr_live_ seguido de 43 letras, dígitos, guiones y guiones bajos.
Crear una clave
- 1
Abre API y agentes
En Gradiently, ve a Ajustes › API y agentes y elige el espacio de trabajo para el que es la clave. Solo los propietarios y administradores de ese espacio de trabajo pueden crear claves.
- 2
Ponle nombre
En Crear una clave, dale un Nombre según dónde vayas a usarla, como Claude Code o Exportación nocturna, para saber cuál revocar más adelante.
- 3
Elige qué puede hacer
En Qué puede hacer, selecciona los permisos que necesita, al menos uno. La siguiente sección explica cada uno.
- 4
Cópiala una vez
Selecciona Crear clave. La clave aparece en Copia tu clave ahora, y es la única vez que se muestra. Cópiala en un gestor de contraseñas o en tu almacén de secretos, y selecciona Ya la he guardado.
Quien crea una clave recibe un correo cuando se crea y cuando se revoca, con su nombre, el inicio de la clave y sus permisos. La lista de Ajustes muestra de cada clave activa su nombre, el inicio de la clave, cuándo se usó por última vez y cuántos permisos tiene.
Permisos
Cada scope de la API es un permiso. Una petición necesita todos los permisos que indica su endpoint, y cada herramienta MCP necesita los permisos de todas las peticiones que hace. Concede solo lo que requiere la tarea.
| Permiso | En Ajustes | Qué permite |
|---|---|---|
designs:read | Leer diseños | Leer marcas, diseños, miniaturas y subidas, renderizar diseños y seguir conjuntos del Designer. |
designs:write | Crear y editar diseños | Crear, cambiar, duplicar, compartir y eliminar diseños, subir y eliminar imágenes, y usar el Designer. |
marks:read | Buscar Marks | Buscar en el Mercado, leer Marks y tus borradores, crear y revisar recetas, y leer las versiones de un Mark. |
marks:claim | Reservar Marks | Reservar un Mark disponible, o uno que otro titular ha puesto a la venta, para el creador de la clave. |
brand:generate | Generar marcas | Generar y adoptar marcas, guardar y cambiar Marks en borrador, y gestionar las versiones de un Mark. |
workspaces:read | Leer el espacio de trabajo | Leer el espacio de trabajo, sus miembros y su registro de auditoría. Con designs:read, leer /api/me. |
personalities:write | Editar marcas | Crear, renombrar y eliminar marcas, y cambiar el Mark, el perfil y el estilo de una marca. |
members:write | Invitar miembros | Enviar invitaciones para unirse al espacio de trabajo. |
Las claves nuevas empiezan con Leer diseños, Crear y editar diseños, Buscar Marks y Generar marcas seleccionados. Reservar Marks está desactivado hasta que lo eliges, porque una reserva te convierte a ti, el creador de la clave, en titular de un Mark.
Rotar una clave
Las claves no caducan, y el nombre y los permisos de una clave no se pueden cambiar después de crearla. Para rotar una clave, o para cambiar lo que puede hacer, sustitúyela:
- 1
Crea la clave nueva
Crea una clave con los permisos que quieras, con un nombre que la distinga de la antigua.
- 2
Pasa tus herramientas a la nueva
Pon la clave nueva en todos los sitios donde se usaba la antigua: tu cliente MCP, tu almacén de secretos o la configuración de despliegue.
- 3
Revoca la clave antigua
Cuando la fecha de usada de la clave antigua deje de cambiar en la lista, revócala.
Revocar una clave
En Ajustes › API y agentes, selecciona Revocar junto a la clave y confirma con Revocar clave. Todo lo que la use deja de funcionar al instante, y no se puede deshacer. Los propietarios y administradores del espacio de trabajo pueden revocar cualquiera de sus claves.
Una clave también deja de funcionar por sí sola cuando su creador sale del espacio de trabajo, baja a un rol inferior a administrador o se desactiva su cuenta. Las claves que creó una persona se revocan cuando se la elimina del espacio de trabajo o se le baja el rol.
Lo que una clave nunca puede hacer
Algunas cosas siempre requieren una persona con la sesión iniciada en Gradiently, sean cuales sean los permisos de la clave:
- Crear, listar o revocar claves.
- Cambiar la cuenta: perfil, correo, contraseña, sesiones iniciadas o eliminarla.
- Acceder a la facturación: planes, pago, cobros, recargas de créditos de IA, Saldo y pagos recibidos. Una reserva o compra que requiere pago se detiene y pide completar el pago en Gradiently.
- Ceder un Mark: transferirlo a otra persona, liberarlo, ponerlo a la venta, renovarlo o publicarlo.
- Pasar la titularidad o la licencia de un Mark al espacio de trabajo. Los Marks que reserva una clave pasan a su creador, y cualquier licencia sigue siendo suya.
- Cambiar quién está en el espacio de trabajo o sus roles, ni renombrar, transferir o eliminar el espacio de trabajo. Con
members:writesolo puede enviar invitaciones. - Llegar a cualquier espacio de trabajo que no sea el suyo, aunque su creador pertenezca a él.
- Usar la administración de Gradiently.
Mantén seguras las claves
Sí
- Crea una clave para cada herramienta o asistente, con su nombre.
- Concede los menos permisos posibles para la tarea.
- Guarda las claves en un gestor de contraseñas, un almacén de secretos o una variable de entorno.
- Revoca una clave en cuanto pueda haberse filtrado, y crea otra nueva.
- Revisa de vez en cuando las fechas de último uso, y revoca las claves que nadie usa.
No
- Subir una clave a un repositorio o pegarla en un archivo de configuración compartido.
- Poner una clave en una página web, una app móvil o cualquier cosa que se ejecute en el dispositivo de otra persona.
- Compartir una clave entre personas o herramientas.
- Enviar una clave por correo o por chat.
- Dejar Reservar Marks activado en una clave que no reserva.
Gradiently solo guarda un hash de cada clave y su inicio para mostrarlo, así que una clave perdida no se puede volver a mostrar: revócala y crea otra. Si crees que alguien ha usado mal una clave, revócala y avísanos.
