Présentation des comptes de services
Les comptes de service seront enfin disponibles de manière fonctionnelle
dans la 1.7.7 qui doit sortir aujourd’hui.
À quoi ça sert ?
À ce jour lorsque vous avez besoin de faire des actions via l’API,
par exemple pour faire une automation avec un outil externe comme n8n
vous devez activer votre clé d’API dans la page de gestion de votre utilisateur.
Inconvénient, si votre clé d’API venait à « fuir » dans la nature alors tous les
documents, espaces d’équipes et organisation dont vous êtes membres deviendraient vulnérables à la fuite d’informations.
Les comptes de service viennent pour palier à ce problème.
Ils vous permettent de créer un utilisateur de type « service » qui vous appartient.
Vous pouvez l’ajouter à vos documents, organisations ou espaces d’équipe comme
n’importe quel utilisateur, avec les mêmes règles avancées afin de restreindre ses droit sur le document.
Utilisation via la console API
Vous pouvez utiliser les service accounts directement depuis la console API (depuis un document, Paramètres > Console API), dans la section « service accounts ».
Cliquez sur « POST /service-accounts » , puis le bouton « Try it out »
Vous pouvez définir une date d’expiration pour la clé API dans le paramètre expiresAt
Cliquez sur le bouton « Execute ».
Vous pourrez voir dans la section « Réponse » :
key: la clé d’API à stocker (elle n’est fournie qu’une seule fois par l’API, en cas de perte il faudra en regénérer une autre)login: l’adresse email en .invalid qui permet d’inviter le compte de service sur un document, un dossier ou un espace d’équipe (via le bouton de partage du doument) et de lui octroyer un rôle (propriétaire, éditeur, lecture seule, …)"
Utilisation avec curl
Attention : À ce jour les comptes de service ne sont accessible que via l’API.
Une interface graphique viendra dans les prochains mois.
Ils ne sont disponible que si votre administrateur système a ajouté la variable GRIST_ENABLE_SERVICE_ACCOUNTS sur le serveur Grist.
L’exemple est fait dans un terminal avec l’outil curl.
Mais vous pouvez bien sûr faire ça avec votre générateur de requêtes préféré (postman, n8n…).
Création d’une clé d’API
$ curl -X GET "https://grist.example/api/service-accounts"" \
-H "Authorization: Bearer ${VOTRE_CLE_D_API}" \
-H "Content-Type: application/json"
[]
Nous n’avons pas de compte de service pour l’instant
curl -X POST "https://grist.example/api/service-accounts" \
-H "Authorization: Bearer ${VOTRE_CLE_D_API}" \
-H "Content-Type: application/json" \
-d '{"label":"Nom du service", "description":"pour le tutoriel", "expiresAt":"2026-10-10"}'
{
"id": 42,
"login": "e3a9d3ef-1cea-42a4-8c91-b13d07568fbe@serviceaccounts.invalid",
"key": "012345678910111213141516171819",
"label": "Nom du service",
"description": "pour le tutoriel",
"expiresAt": "2026-10-10T00:00:00.000Z",
"hasValidKey": true
}
Attention: Sauvegardez bien la clé key celle-ci ne vous sera affichée que lors de la création du compte de service.
Le login est le compte mail que vous devez renseigner pour inviter le compte de service à une ressource.
L’id est ce qui vous permettra de manipuler le compte de service via l’API.
Ajout du compte de service à un document
Vous pouvez l’ajouter comme n’importe quel utilisateur sur un document.
Et privilégiez le moindre accès pour renforcer la sécurité. Dans l’exemple qui suit, nous n’avons besoin que de consulter les données du document, donc nous définissons un accès en lecture seule :
Vérifier que l’on a accès aux données document
curl -X GET "https://grist.example/api/docs/A1B2C34567890/tables/Mes_messages/records" \
-H "Authorization: Bearer 012345678910111213141516171819" \
-H "Content-Type: application/json" \
{
"records": [
{
"id": 1,
"fields": {
"texte": "Bonjour la suite",
"cacher_aux_robots": false
}
},
{
"id": 2,
"fields": {
"texte": "Comment ça va ?",
"cacher_aux_robots": false
}
},
{
"id": 3,
"fields": {
"texte": "Ce message est reservé aux humains",
"cacher_aux_robots": false
}
}
]
}
Changer les accès et vérifier ce que l’on voit
On a une règle ACL qui nous permet de choisir à quelles lignes on donne accès.
Si on coche certaines lignes elles seront masquées au compte de service
Et si on liste de nouveau ce que l’on voit il ne reste que ce que l’on souhaite.
{
"records": [
{
"id": 1,
"fields": {
"texte": "Bonjour la suite",
"cacher_aux_robots": false
}
}
]
}
Révoquer la clé d’API du compte de service
On peut révoquer la clé
curl -X DELETE "https://grist.example/api/service-accounts/42/apikey" \
-H "Authorization: Bearer ${VOTRE_CLE_D_API}" \
-H "Content-Type: application/json"
Supprimer le compte de service
Mais aussi le supprimer si on le souhaite
curl -X DELETE "https://grist.example/api/service-accounts/42" \
-H "Authorization: Bearer ${VOTRE_CLE_D_API}" \
-H "Content-Type: application/json"
En conclusion
La totalité de l’API des comptes est documentée dans le centre d’aide de Grist. Et également disponible via la console API.
merci pour le tuto