Authentification

Chaque requête est authentifiée par une clé d'API. Envoyez-la sous forme de jeton Bearer :

Authorization: Bearer gsk_live_xxx

Si un jeton Bearer est peu pratique dans votre stack, l'en-tête x-api-key: gsk_live_xxx est également accepté. Sans clé, chaque requête reçoit 401 avec title: invalid_key.

Format de la clé

gsk_live_<id>_<secret> ou gsk_test_<id>_<secret>. Une clé gsk_live effectue un vrai travail et est facturée. Une clé gsk_test fonctionne dans le bac à sable : les outils sont simulés et rien n'est facturé ; les annonces, les leads et les autres données réelles ne peuvent pas être modifiés avec elle. Choisissez le type de clé lors de sa création.

Le secret n'est affiché qu'une seule fois, à la création. GREM ne conserve que son hachage : une clé perdue ne peut donc pas être récupérée - créez-en une nouvelle et révoquez l'ancienne.

Gestion des clés

Dans l'espace personnel, API → Clés :

• Créer une clé avec un libellé. Les paramètres avancés permettent de choisir les scopes et une durée de validité en jours. Sans choix, la clé reçoit tous les scopes.
• Faire pivoter - émettre un nouveau secret ; l'ancien continue de fonctionner pendant 24 heures, le temps de le remplacer dans votre intégration.
• Révoquer - la clé cesse de fonctionner immédiatement et définitivement.

Le statut de la clé est affiché dans la liste : active - fonctionne ; suspended - accès à l'API suspendu par un administrateur (réversible, la clé n'est pas détruite) ; revoked - révoquée. Une clé avec une date d'expiration n'est plus acceptée une fois celle-ci passée (401).

Clés d'agence

Le propriétaire ou un manager d'une agence peut émettre une clé au nom de l'agence : basculez la liste des clés sur le périmètre de l'agence. Une telle clé :

• voit les annonces et les leads de l'agence, et non les personnels ;
• peut prendre des leads dans le pool commun de l'agence et les y remettre (Leads) ;
• peut transférer des annonces dans l'agence et leur attribuer un agent (Annonces).

Une clé peut être liée à un seul agent - elle agit alors en tant que cet agent, avec ses permissions.

Scopes

Chaque clé porte un ensemble de scopes. Un appel sans le scope requis renvoie 403 avec title: forbidden_scope. Le scope nécessaire à une opération est indiqué dans sa description dans /openapi.json (champ x-required-scope).

Sans aucun scope, vous pouvez appeler GET /ping, GET /me, GET /dictionaries, GET /objects, GET /voices, GET /tools/status et GET /works.

Quelle est cette clé

curl https://developers.grem.capital/api/v1/me \
  -H "Authorization: Bearer gsk_live_xxx"

GET /me renvoie l'identifiant et le préfixe de la clé, son titulaire (subjectType : user ou agency, subjectId, et agencyMemberId pour une clé d'agent), les scopes accordés, les limites de débit applicables à cette clé précise (rateLimit.rpm par minute et rateLimit.rpd par jour) et la date d'expiration. Le secret n'est jamais renvoyé. Gratuit.

Sécurité

• Conservez les clés dans des variables d'environnement côté serveur ou dans un gestionnaire de secrets.
• Utilisez une clé distincte par intégration, avec uniquement les scopes nécessaires - en révoquer une n'affecte pas les autres.
• Faites pivoter les clés selon un calendrier régulier.
• Les requêtes ne sont acceptées qu'en HTTPS.

Voir aussi

• Erreurs - 401 et 403 en détail.
• Limites et facturation - ce que signifient rpm et rpd.