Claves de API y tokens de acceso

Una clave de API es la forma en que tus programas acceden a la API de LinkHarbor. Pertenece a un espacio de trabajo, no a una persona, y puede hacer exactamente lo que le permitas mediante los scopes. Para las llamadas en sí, cambias la clave por un token de acceso de corta duración.

#¿Quién puede crear claves de API?

• Los propietarios y admins del espacio de trabajo; los editores y visualizadores solo ven la tarjeta «Apps conectadas» en «Callback y API»
• Desde Creator Pro; en Creator Free la tarjeta dice «Las claves de API están disponibles desde Creator Pro.»
• Activas a la vez: hasta 5 claves en Creator Pro, hasta 20 en Creator Agency y hasta 50 en Enterprise

Cuando se alcanza el límite, crear una clave falla con 409 limit_reached. Elimina antes una clave que ya no necesites.

#Crear una clave de API

1. Abre «Callback y API» en la navegación
2. En la tarjeta «Claves de API», haz clic en «+ Crear nueva clave»
3. En «Nombre (opcional)», escribe un nombre con el que reconozcas la clave más adelante, por ejemplo «Pipeline de CI/CD» o «Sincronización de la tienda»
4. En «Ámbitos», elige «Lectura» o «Escritura» para cada área
5. Haz clic en «Crear clave»
6. Copia de inmediato el «Secreto de la clave (privado)» y guárdalo en un lugar seguro
7. Cierra el diálogo; el ID de la clave lo encuentras en la lista en cualquier momento

«Nombre (opcional)»

Hasta 64 caracteres. Sin nombre, la clave aparece en la lista como «Clave de API #ID».

«Ámbitos»

Se requiere al menos uno. «Escritura» incluye automáticamente «Lectura» para la misma área. Las estadísticas y los pagos de mecenas son de solo lectura, y las plantillas del espacio de trabajo, de solo escritura. Todos los scopes se explican en Scopes en detalle.

«Secreto de la clave (privado)»

Empieza por lt_ y se muestra exactamente una vez («⚠️ Solo visible una vez — ¡cópialo ahora!»). LinkHarbor solo guarda un hash del secreto y no puede volver a mostrártelo después.

«ID de clave:»

16 caracteres formados por dígitos y las letras mayúsculas A–F, por ejemplo 6F668EA6598B0692. No es secreto y aparece en la lista con un botón para copiarlo.

#La lista de claves

Cada clave activa muestra su nombre, el estado «Activo», el ID de la clave, sus scopes, «Creado:» y «Último uso:» o «Aún sin usar». La hora del último uso se actualiza en cada llamada hecha con la clave, como máximo una vez por minuto. «↺ Actualizar» vuelve a cargar la lista.

#Cambiar la clave por un token de acceso

curl -X POST https://dock.at-harbor.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'

{ "token": "eyJhbGciOiJIUzI1NiIs…", "expires_in": 900 }

token

El token de acceso. Lo envías en cada petición como Authorization: Bearer <token>.

expires_in

Validez en segundos: 900, es decir, 15 minutos. No hay refresh token: cuando caduca, simplemente pides un token nuevo con el ID y el secreto de la clave.

El token representa al espacio de trabajo y lleva exactamente los scopes de la clave. No tiene un rol como una persona: los endpoints que el panel reserva a propietarios y admins (miembros, facturación, gestión de dominios, webhooks, ajustes del espacio de trabajo) se rechazan siempre para los tokens de claves de API. Las excepciones son los enlaces cortos y las plantillas del espacio de trabajo, que funcionan con el scope correspondiente, y la lectura de los secretos de callback (sin el secreto en texto plano) con read:workspaces.

#Intentos fallidos y bloqueo

Con api_key_locked, el tiempo restante está en details.retry_after_sec. Un intercambio correcto pone el contador a cero.

#Eliminar y sustituir una clave

1. Haz clic en «Eliminar» junto a la clave
2. Escribe DELETE para confirmar
3. Haz clic en «Eliminar permanentemente»

La clave deja de funcionar de inmediato; los tokens de acceso ya emitidos también dejan de funcionar en ese momento y reciben 401 invalid_token. No hay botón para rotarla. Para cambiar de clave, crea una nueva, pasa tu programa a ella y después elimina la antigua.

#Cuando bajas de plan

Si el espacio de trabajo pasa a Creator Free, se revocan todas las claves de API. Si pasa a un plan con menos claves, se conservan las más recientes y se revocan las demás. Las claves revocadas no vuelven con una mejora posterior: en ese caso creas otras nuevas. Los propietarios reciben un correo con la lista de funciones desactivadas. Más en Cancelar y bajar de plan.

#Mantenerla segura

• Guarda el secreto solo en un gestor de secretos o en variables de entorno, nunca en el código fuente ni en un repositorio Git
• No lo uses nunca en código que se ejecute en el navegador o en una app en el dispositivo del usuario
• Crea una clave distinta para cada aplicación, con los menos scopes posibles
• Elimina enseguida las claves que ya no necesites
• Si sospechas de una filtración: elimina la clave y crea una nueva