Claves de API y la API pública

Para qué sirve una clave

Una clave de API permite que el propio código de un espacio de trabajo, un script, un servidor u otro producto, lea, cree y edite sus proyectos, lea sus tareas y añada tareas, sin que nadie inicie sesión. Cada clave pertenece a un espacio de trabajo, lleva los permisos elegidos al crearla y se envía como token bearer a la API pública bajo /api/v1.

• La clave completa se muestra una sola vez, al crearla. La API guarda solo un hash SHA-256 de ella y un prefijo corto como nst_live_3f9a, así que una clave perdida no se puede mostrar de nuevo: revócala y crea otra.
• Cada llamada hecha con una clave cuenta para las API requests del espacio de trabajo en la página de facturación, y actualiza el Last used de la clave.
• Los datos de ejemplo dan a Forma Studio y a Monogram una clave a cada uno, para que la lista no esté vacía. Sus secretos nunca se mostraron, así que no autentican nada: crea la tuya para probar la API.

Crear una clave

1. 01

   Abre la pestaña API keys

   En el panel, abre Settings, luego API keys, y pulsa Create key. La pestaña aparece solo para un rol que tiene keys.manage.
2. 02

   Ponle nombre y elige qué puede hacer

   Dale un Key name, como "Production server", y marca lo que puede hacer la clave bajo "What the key may do". Leer proyectos y leer tareas vienen marcados de inicio.
3. 03

   Copia el secreto

   "Copy the secret now": el cuadro de diálogo muestra la clave completa una vez, con Copy key. Guárdala en tu gestor de secretos y pulsa I stored it. Cerrar el cuadro la olvida.

Un espacio de trabajo con pago vencido más allá de su periodo de gracia, o cancelado, no puede crear claves: consulta un pago fallido.

Revocar una clave

Pulsa Revoke en la fila de la clave y confirma con Revoke key: "Anything that uses this key stops working at once. This cannot be undone." Una clave revocada se queda en la lista, marcada como Revoked, debajo de las activas. Crear y revocar una clave se escriben ambas en el registro de actividad del espacio de trabajo.

Llamar a la API con una clave

Envía la clave como Authorization: Bearer en cada petición. Las respuestas tienen el mismo envoltorio que el resto de la API, { "success": true, "data": ..., "message": "" }.

Lista los proyectos del espacio de trabajo, el cambio más reciente primero, como máximo 100:

curl http://localhost:8000/api/v1/projects -H "Authorization: Bearer <your key>"

Lista las tareas de un proyecto, en el orden del tablero, con el id del proyecto de esa lista (como prj_01):

curl http://localhost:8000/api/v1/projects/prj_01/tasks -H "Authorization: Bearer <your key>"

Añade una tarea. Solo el título en inglés es obligatorio; status es backlog (el valor por defecto), in_progress, review o done, priority es low, normal o high, y dueDate se escribe YYYY-MM-DD:

curl -X POST http://localhost:8000/api/v1/projects/prj_01/tasks \
  -H "Authorization: Bearer <your key>" -H "Content-Type: application/json" \
  -d '{"translations":{"en":{"title":"Check the launch email"}},"priority":"high"}'

La tarea queda al final de su columna, y el tablero y el registro de actividad la muestran como hecha por la persona que creó la clave.

Crea un proyecto, o cambia uno, con los mismos campos que el panel lateral de proyecto del panel: translations (el name en inglés obligatorio, hasta 120 caracteres, y una description opcional), y opcionalmente status (in_progress, review, blocked o completed), ownerId (un miembro), dueDate y progress (de 0 a 100):

curl -X POST http://localhost:8000/api/v1/projects \
  -H "Authorization: Bearer <your key>" -H "Content-Type: application/json" \
  -d '{"translations":{"en":{"name":"Launch site"}},"status":"in_progress"}'

PATCH /api/v1/projects/<id> acepta cualquiera de los mismos campos. Toda escritura se ejecuta como el creador de la clave, con las comprobaciones del panel: el creador debe seguir teniendo projects.write en el espacio de trabajo, y un espacio con pago vencido cuyo periodo de gracia se agotó no puede crear proyectos.

Cuando se rechaza una llamada

El message es una frase en el idioma de la petición: la de arriba, o la frase general del estado. Un campo del cuerpo que la ruta no acepta responde 400.

Quién puede gestionar las claves

Forma parte de la matriz de roles de cada espacio de trabajo, así que el propietario puede concederlo a otro rol.

• Equipo y roles
• Referencia de la API