Clés d'API et API publique

À quoi sert une clé

Une clé d'API permet au code propre d'un espace de travail, un script, un serveur ou un autre produit, de lire, créer et modifier ses projets, de lire ses tâches et d'ajouter des tâches, sans que personne ne se connecte. Chaque clé appartient à un seul espace de travail, porte les permissions choisies à sa création et s'envoie comme jeton bearer à l'API publique sous /api/v1.

• La clé complète n'est montrée qu'une fois, à sa création. L'API ne garde qu'un hachage SHA-256 de celle-ci et un court préfixe comme nst_live_3f9a : une clé perdue ne peut donc pas être montrée de nouveau, révoquez-la et créez-en une autre.
• Chaque appel fait avec une clé compte dans les API requests de l'espace de travail sur la page Billing, et met à jour le Last used de la clé.
• Le seed donne une clé à Forma Studio et à Monogram, pour que la liste ne soit pas vide. Leurs secrets n'ont jamais été montrés : elles n'authentifient donc rien, créez la vôtre pour essayer l'API.

Créer une clé

1. 01

   Ouvrez l'onglet API keys

   Dans le tableau de bord, ouvrez Settings, puis API keys, et appuyez sur Create key. L'onglet n'apparaît que pour un rôle qui détient keys.manage.
2. 02

   Nommez-la et choisissez ce qu'elle peut faire

   Donnez-lui un Key name, comme « Production server », et cochez ce que la clé peut faire sous « What the key may do ». La lecture des projets et la lecture des tâches sont cochées au départ.
3. 03

   Copiez le secret

   « Copy the secret now » : la boîte de dialogue montre la clé complète une fois, avec Copy key. Rangez-la dans votre gestionnaire de secrets, puis appuyez sur I stored it. Fermer la boîte de dialogue l'oublie.

Un espace de travail en retard de paiement au-delà de son délai de grâce, ou annulé, ne peut pas créer de clés : voir un paiement échoué.

Révoquer une clé

Appuyez sur Revoke sur la ligne de la clé et confirmez avec Revoke key : « Anything that uses this key stops working at once. This cannot be undone. » Une clé révoquée reste dans la liste, marquée Revoked, sous les clés actives. La création et la révocation d'une clé sont toutes deux écrites dans le journal d'activité de l'espace de travail.

Appeler l'API avec une clé

Envoyez la clé en Authorization: Bearer à chaque requête. Les réponses ont la même enveloppe que le reste de l'API, { "success": true, "data": ..., "message": "" }.

Listez les projets de l'espace de travail, la modification la plus récente d'abord, 100 au plus :

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

Listez les tâches d'un projet, dans l'ordre du tableau, avec l'identifiant du projet issu de cette liste (comme prj_01) :

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

Ajoutez une tâche. Seul le titre anglais est obligatoire ; status vaut backlog (par défaut), in_progress, review ou done, priority vaut low, normal ou high, et dueDate s'écrit 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 tâche arrive en fin de sa colonne, et le tableau et le journal d'activité l'affichent comme créée par la personne qui a créé la clé.

Créez un projet, ou modifiez-en un, avec les mêmes champs que le panneau de projet du tableau de bord : translations (le name anglais obligatoire, jusqu'à 120 caractères, et une description facultative), et en option status (in_progress, review, blocked ou completed), ownerId (un membre), dueDate et progress (0 à 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> accepte n'importe lequel des mêmes champs. Chaque écriture s'exécute au nom du créateur de la clé, avec les vérifications du tableau de bord : le créateur doit encore détenir projects.write dans l'espace de travail, et un espace de travail en retard de paiement dont le délai de grâce est épuisé ne peut pas créer de projets.

Quand un appel est refusé

Le message est une phrase dans la langue de la requête : celle ci-dessus, ou la phrase générale du statut. Un champ de corps que la route n'accepte pas répond 400.

Qui peut gérer les clés

Elle fait partie de la matrice de rôles de chaque espace de travail : le propriétaire peut donc l'accorder à un autre rôle.

• Équipe et rôles
• Référence de l'API