Présentation de l’API
Faites travailler Geta.Team depuis votre propre backend, avec une clé API.
L’API Geta.Team permet à votre propre backend de travailler avec votre compte : suivre les espaces que vous avez créés pour vos clients, et être prévenu de chaque changement par un webhook.
URL de base
https://dash.geta.team/api/v1Les corps des requêtes et des réponses sont en JSON (Content-Type: application/json).
Authentification
Créez une clé dans votre dashboard, dans Compte, section API :
- Donnez-lui un nom.
- Choisissez son accès : lecture et écriture, ou lecture seule (suivre vos espaces, sans rien modifier).
- Indiquez les adresses IP depuis lesquelles elle sera utilisée : une IP ou une
plage par ligne, comme
203.0.113.10ou198.51.100.0/24. Obligatoire : un appel venant d’une autre adresse est refusé, même avec la bonne clé. Le dashboard propose d’ajouter votre IP actuelle.
Puis copiez-la. La clé n’est affichée qu’une fois ; nous n’en gardons qu’une empreinte. Vous pouvez modifier les adresses d’une clé à tout moment.
Envoyez-la dans l’en-tête Authorization de chaque appel :
curl https://dash.geta.team/api/v1/me \
-H "Authorization: Bearer gat_sk_..."{ "id": 42, "email": "[email protected]" }- Un compte a au plus 10 clés actives. Révoquez-en une dans le dashboard et tout programme qui l’utilise s’arrête aussitôt.
- Chaque nouvelle clé envoie un email d’alerte au titulaire du compte, avec le nom de la clé et ses premiers caractères (jamais la clé elle-même).
- Gardez les clés sur votre serveur : jamais dans une page web ni une application mobile.
Erreurs
Une erreur, c’est un code HTTP et un corps qu’un programme peut lire :
{ "error": { "code": "not_found", "message": "No such workspace" } }| Statut | code | Signification |
|---|---|---|
| 400 | invalid_request | Un champ manque ou est faux ; message dit lequel |
| 401 | unauthorized | Pas de clé, une clé inconnue ou révoquée |
| 403 | ip_not_allowed | La clé n’est pas autorisée depuis cette adresse ; ip indique l’adresse vue : ajoutez-la à la clé |
| 403 | insufficient_scope | La clé n’a pas l’accès que demande cet appel |
| 404 | not_found | Aucun espace de ce numéro sur votre compte |
| 429 | rate_limited | Trop de requêtes pour cette clé, réessayez dans une minute |
| 500 | internal_error | Un problème de notre côté ; notre équipe est alertée |
Les messages d’erreur sont en anglais ; fiez-vous au code.
Limite de débit
120 requêtes par minute et par clé. Au-delà, l’API répond 429 avec
rate_limited ; les en-têtes RateLimit-* indiquent combien il en reste et quand
la fenêtre se réinitialise.
Référence interactive et OpenAPI
Chaque appel, ses champs, ses réponses et ses erreurs, avec un bouton pour l’essayer avec votre clé : la référence interactive (en anglais ; ajoutez votre IP actuelle à la clé pour essayer depuis votre navigateur). Elle est générée depuis le fichier OpenAPI 3.1, geta-team-api-v1.yaml, que vous pouvez aussi importer dans Postman, Insomnia ou un générateur de client.