Copier pour l’IA

Authentification

Découvrez comment structurer vos requêtes authentifiées vers les serveurs de Cord.

Bearer Tokens

L’API de Cord utilise des jetons porteurs (Bearer Tokens) pour authentifier les requêtes entrantes. Vous devez envoyer la clé API que vous avez générée dans le tableau de bord dans un en-tête HTTP Authorization.

Toutes les requêtes doivent passer par HTTPS. Les requêtes sans authentification ou envoyées en HTTP simple échouent.

Exemple de requête :

curl -X GET "https://cordhq.app/api/v1/cotizaciones" \
     -H "Authorization: Bearer sk_live_tU..."

Clés secrètes et clés publiables

Cord propose trois types de clés :

1. Secrètes (sk_) : uniquement sur vos serveurs. En lecture seule ou en lecture et écriture sur toute l’API.
2. Restreintes (rk_) : uniquement sur vos serveurs, avec un droit par ressource (none, read ou write). Utilisez-les pour donner à une intégration tierce exactement ce dont elle a besoin. Voir les clés restreintes.
3. Publiables (pk_) : pour le navigateur, avec une liste fixe de routes.

Masquage automatique des données

Les clés publiables sont soumises à des restrictions de sécurité automatiques imposées par l’API. Par exemple, si vous interrogez l’API des produits avec une clé publiable, le serveur de Cord omet automatiquement le champ costo (marge) pour que les visiteurs de votre site ne puissent pas découvrir vos marges bénéficiaires.

De plus, une clé publiable ne peut être utilisée que sur quatre routes : GET /api/v1/productos, POST /api/v1/cotizaciones, GET /api/v1/elements/config et POST /api/v1/elements/ai-draft. Toute autre route répond 403 insufficient_scope. La requête doit aussi envoyer un en-tête Origin ou Referer qui correspond aux domaines autorisés de votre organisation, configurés dans Paramètres › Générateur de devis intégrable. Une clé pk_live_ sans domaines configurés répond 403 origin_allowlist_required ; une clé pk_test_ est acceptée depuis n’importe quelle origine.

Clés restreintes

Une clé rk_ porte un niveau par ressource. Cord déduit la ressource de la route : une nouvelle route de l’API est donc interdite par défaut aux clés restreintes existantes jusqu’à ce que vous leur en donniez le droit.

Ressource	Routes
cotizaciones	/api/v1/cotizaciones/*
clientes	/api/v1/clientes/*
productos	/api/v1/productos/*
facturas	/api/v1/facturas/*
cobranza	/api/v1/cobranza
tareas	/api/v1/tareas
eventos	/api/v1/events
webhooks	/api/v1/webhooks/*
elements	/api/v1/elements/*
test_helpers	/api/v1/test_helpers/*
setup	/api/v1/setup/*

read autorise GET ; write autorise en plus la création, la modification et les actions. GET /api/v1/me répond à n’importe quelle clé secrète ou restreinte. Sur le serveur MCP, une clé restreinte applique le même niveau par ressource à chaque outil (voir droits par outil). Sans le droit nécessaire, la réponse est 403 insufficient_permissions et nomme la ressource.

IP autorisées

Sur une clé sk_ ou rk_, vous pouvez définir jusqu’à 20 IP ou plages CIDR (IPv4 ou IPv6). Cord compare l’IP d’origine enregistrée par son réseau de distribution, et non un en-tête que le client peut écrire : X-Forwarded-For ne permet donc pas de contourner la liste. Une requête depuis une autre IP répond 403 ip_not_allowed et est consignée dans le journal d’audit de votre organisation, une fois par heure et par IP.

Les clés publiables se limitent par domaine dans Paramètres › Générateur de devis intégrable, et non par IP.

Expiration et renouvellement

Lorsque vous créez une clé, vous pouvez choisir qu’elle expire au bout de 7, 30, 90 ou 365 jours ; ensuite, elle répond 401 key_expired. Renouveler crée une nouvelle clé avec les mêmes droits, les mêmes IP et la même version de l’API, et maintient l’ancienne active pendant la durée que vous choisissez (immédiatement, 1 heure, 24 heures ou 7 jours) le temps de mettre à jour vos systèmes. La clé en période de grâce ne compte plus dans la limite de votre offre. La création, la modification, le renouvellement et la révocation des clés sont consignés dans le journal d’audit, avec l’auteur et l’IP d’origine.

Clés incluses par offre

Chaque offre inclut un nombre maximal de clés actives : 2 avec l’offre Gratuite, 5 avec Starter, 20 avec Professionnel, 50 avec Scale et 200 avec Developer. Sont comptées les clés secrètes, restreintes et publiables qui ne sont ni révoquées, ni expirées, ni en période de grâce après un renouvellement ; les connexions autorisées par OAuth (Zapier, Make) ne comptent pas. Une fois la limite atteinte, le Workbench ne vous laisse pas en créer une autre tant que vous n’en avez pas révoqué une.

Si votre organisation se retrouve avec plus de clés actives que son offre n’en inclut (par exemple, après un passage à une offre inférieure), les plus anciennes continuent de fonctionner et celles qui dépassent le quota répondent 402 subscription_key_limit jusqu’à ce que vous révoquiez des clés ou passiez à une offre supérieure.

Vérification rapide de l’identité

Pour vérifier que votre clé API fonctionne correctement et savoir à quel compte elle appartient, utilisez l’endpoint me :

curl -X GET "https://cordhq.app/api/v1/me" \
     -H "Authorization: Bearer sk_live_tU..."