Skip to Content
TillorManuel

API HTTP

Clés API, URL de base et authentification pour l'API REST de Tillor

Dernière mise à jour le

L'API Tillor est une API REST. Authentifiez-vous avec une clé API et envoyez les bons en-têtes à chaque requête. Les clés API sont par compte - une seule clé fonctionne pour toutes les organisations auxquelles vous avez accès.

Référence de l'API et OpenAPI

  • Référence de l'API - Chaque endpoint avec ses paramètres et des exemples ; testez les requêtes directement dans le navigateur
  • Spécification OpenAPI - Documentation complète de l'API au format JSON pour la génération de code ou l'import dans Postman/Insomnia

Clés API

Création

Vous créez les clés API dans l'application Tillor via le menu utilisateur sous Compte > Clés API (repère 1 = menu, repère 2 = Clés API sur la capture d'écran). Vous pouvez aussi les créer via l'API avec une session connectée (pas de clé API). Voir la spécification OpenAPI sous le tag api-keys pour les chemins et les schémas de requête et de réponse.

Clés API dans les paramètres du compte

La clé brute n'est renvoyée qu'une seule fois lors de la création ou de la régénération. Conservez-la en lieu sûr ; vous ne pourrez plus la récupérer ensuite.

Limiter les droits

Par défaut, une clé peut tout ce que vous pouvez vous-même, dans chaque organisation dont vous êtes membre. Dans la fenêtre de la clé, activez Limiter aux autorisations sélectionnées et choisissez les droits dont l'intégration a besoin, par exemple uniquement lire les factures. Une clé limitée reçoit, dans chaque organisation, l'intersection de ses droits et de votre appartenance à cette organisation : une clé ne peut jamais faire plus que vous. Un appel en dehors des droits choisis reçoit 403 Forbidden, comme un utilisateur sans ce droit. Une modification des droits s'applique en moins d'une minute. Via l'API : scopes (liste d'identifiants de droits comme invoices:read, ou null pour tout) à la création et à la mise à jour d'une clé.

Utilisation

Envoyez la clé API dans l'en-tête x-api-key :

x-api-key: tkn_xxx

Les clés utilisent le préfixe tkn_. Pour les endpoints d'organisation, l'identifiant de l'organisation figure dans le chemin (/orgs/org_abc123/...) ; un en-tête distinct n'est pas nécessaire.

Limites de débit

  • Par défaut : 5000 requêtes par 60 secondes par clé
  • En cas de dépassement : 429 Too Many Requests avec Retry-After
  • Chaque réponse à une clé API contient les en-têtes IETF RateLimit-* :
RateLimit-Limit: 5000
RateLimit-Remaining: 4999
RateLimit-Reset: 58
RateLimit-Policy: 5000;w=60

RateLimit-Reset est le nombre de secondes avant le redémarrage de la fenêtre actuelle. Les clients de navigateur peuvent lire ces en-têtes via CORS (Access-Control-Expose-Headers).

Sécurité

Attention

  • Jamais d'exposition de clés API dans du code côté client ou dans des dépôts publics
  • Régénérez les clés régulièrement via Régénérer dans l'application (OpenAPI : POST /api/api-keys/:id/renew)
  • Supprimez les clés inutilisées avec DELETE /api/api-keys/:id

URL de base et contexte d'organisation

URL de base : https://tillor.eu (ou l'URL de votre déploiement ; OpenAPI mentionne {APP_URL}/api)

Chemins d'organisation : ajoutez l'identifiant de l'organisation dans le chemin :

/api/orgs/:orgId/...

Exemple :

GET https://tillor.eu/api/orgs/org_abc123/customers

En-tête requis pour les endpoints d'organisation : x-api-key: tkn_xxx. L'identifiant de l'organisation figure dans le chemin.

Exemple : cURL

curl -X GET "https://tillor.eu/api/orgs/org_abc123/customers" \
  -H "x-api-key: tkn_xxx" \
  -H "Content-Type: application/json"

Intégrations (marketplace)

Les intégrations d'organisation (auparavant « apps » dans l'API) utilisent une ressource par type sous /api/orgs/:orgId/integrations/{integrationType}. Les permissions requises sont organization:integrations:read et organization:integrations:write (elles remplacent organization:apps:*).

MéthodeCheminDescription
GET/integrations/{integrationType}Statut (installed, available) et settings masqués
POST/integrations/{integrationType}Installer (settings facultatif dans le corps ; OAuth peut renvoyer redirectUrl)
PUT/integrations/{integrationType}Mettre à jour les réglages (settings dans le corps)
DELETE/integrations/{integrationType}Désinstaller

Avec GET et après PUT, settings ne contient que les champs publics, plus { configured: true } par champ secret. Les mots de passe, clés API et jetons OAuth ne sont pas renvoyés. Laissez les champs secrets vides lors d'un PUT pour conserver la valeur existante.

Voir la spécification OpenAPI (tag integrations) pour les schémas exacts.

Voir aussi

Cette page t'a-t-elle été utile ?

Développeurs

Accès à l'API, webhooks et événements en temps réel pour les intégrations

MCP

Connectez des outils d'IA à Tillor via https://mcp.tillor.dev

Sur cette page

Référence de l'API et OpenAPIClés APICréationLimiter les droitsUtilisationLimites de débitSécuritéURL de base et contexte d'organisationExemple : cURLIntégrations (marketplace)Voir aussi