Authentification

Utilisez une clé API pour votre propre backend ou vos automatisations. Utilisez OAuth lorsque votre application demande à d'autres utilisateurs de Make Agent Fast de lui accorder un accès. Les deux types d'identifiants appellent les mêmes ressources /api/v1 et respectent les mêmes portées, droits liés au forfait, isolation entre locataires et limites de débit.

Clés API#

Un forfait payant actif est requis pour créer et utiliser une clé API publique.

1. Ouvrez Dashboard → Settings → Developer.
2. Saisissez un nom qui identifie le service et l'environnement, par exemple Production lead export.
3. Sélectionnez les portées minimales dont le service a besoin.
4. Choisissez une expiration : 30 jours, 90 jours, un an ou jamais.
5. Créez la clé et copiez immédiatement la valeur maf_live_....

Make Agent Fast stocke un hachage SHA-256 plutôt qu'un texte en clair récupérable. Le tableau de bord affiche ensuite un préfixe sans risque, les portées, l'expiration, la date de dernière utilisation et l'état de révocation.

Authorization: Bearer maf_live_...

Envoyez l'en-tête depuis du code serveur :

curl --fail-with-body https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"

L'absence d'identifiants renvoie 401 authentication_required. Une clé invalide, expirée ou révoquée renvoie 401 invalid_api_key. Une clé dont le compte n'a plus de forfait payant actif renvoie 403 subscription_required.

Faire tourner ou révoquer une clé#

Créez une clé de remplacement avant de révoquer l'ancienne. Déployez la nouvelle clé, effectuez une vraie requête, vérifiez son x-request-id, puis cliquez sur Revoke sur l'ancienne clé. La révocation est immédiate et irréversible.

Dans les paramètres Developer, Edit vous permet de modifier le nom et les portées d'une clé active ; la modification s'applique immédiatement à la même clé. Son expiration et son jeton ne peuvent pas être modifiés : créez une clé de remplacement pour obtenir une nouvelle expiration ou un jeton renouvelé.

Applications OAuth#

OAuth est destiné aux logiciels qui se connectent à des comptes appartenant à d'autres utilisateurs de Make Agent Fast. Il utilise le flux Authorization Code avec PKCE (S256) et n'émet ni n'exige de secret client. L'identifiant client (client ID) est public ; les codes d'autorisation, les jetons d'accès, les jetons d'actualisation et le vérificateur PKCE sont sensibles.

1. Enregistrer l'application#

Ouvrez Dashboard → Settings → Developer → OAuth applications. Ajoutez :

• Un nom d'application de 2 à 100 caractères.
• Entre 1 et 10 URL de redirection exactes.
• Les portées maximales que votre application peut demander.

Les URL de redirection en production doivent utiliser HTTPS et ne peuvent contenir ni identifiants ni fragments. L'URI complète doit correspondre à une valeur enregistrée lors de l'autorisation et de l'échange du jeton. Les applications nouvellement soumises ont le statut pending ; l'autorisation ne fonctionne qu'une fois l'application examinée et marquée approved.

Le propriétaire de la plateforme examine les identifiants client en attente grâce au workflow audité oauth:review. Conservez l'identifiant client affiché après la soumission ; son statut est visible sur la page Developer, et les applications rejetées incluent la décision de l'examen avant de pouvoir être soumises à nouveau.

2. Générer les valeurs PKCE#

Générez un nouveau vérificateur pour chaque tentative d'autorisation et conservez-le dans la même session protégée et de courte durée que state.

import { createHash, randomBytes } from "node:crypto";

const verifier = randomBytes(48).toString("base64url");
const challenge = createHash("sha256").update(verifier).digest("base64url");
const state = randomBytes(24).toString("base64url");

Le vérificateur doit contenir de 43 à 128 caractères PKCE compatibles avec les URL. Seul code_challenge_method=S256 est accepté.

3. Rediriger l'utilisateur pour le consentement#

https://makeagent.fast/oauth/authorize
  ?client_id=maf_app_...
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
  &response_type=code
  &scope=sites%3Aread%20leads%3Aread
  &state=RANDOM_STATE
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256

L'utilisateur se connecte, examine les portées demandées, puis autorise ou refuse l'accès. En cas de succès, Make Agent Fast redirige vers l'URI enregistrée exacte avec code et le state d'origine. En cas de refus, il envoie error=access_denied ainsi que le state d'origine s'il a été fourni.

Rejetez le callback si state ne correspond pas exactement à la valeur stockée pour cette session de navigateur.

4. Échanger le code d'autorisation#

Le code d'autorisation expire au bout de 10 minutes et ne peut être utilisé qu'une seule fois.

curl --fail-with-body https://makeagent.fast/api/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=maf_app_..." \
  --data-urlencode "code=$AUTHORIZATION_CODE" \
  --data-urlencode "redirect_uri=https://app.example.com/oauth/callback" \
  --data-urlencode "code_verifier=$PKCE_VERIFIER"

{
  "access_token": "maf_live_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "maf_refresh_...",
  "scope": "sites:read leads:read"
}

Le jeton d'accès est valable une heure. Le jeton d'actualisation est valable jusqu'à 90 jours, sauf s'il est renouvelé ou révoqué plus tôt.

5. Renouveler le jeton d'actualisation#

Chaque actualisation réussie révoque à la fois le jeton d'actualisation soumis et son jeton d'accès précédent, puis renvoie une nouvelle paire. Enregistrez la nouvelle paire de manière atomique avant de supprimer l'état de la réponse précédente.

curl --fail-with-body https://makeagent.fast/api/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "client_id=maf_app_..." \
  --data-urlencode "refresh_token=$REFRESH_TOKEN"

La réutilisation d'un code d'autorisation ou d'un jeton d'actualisation déjà renouvelé renvoie invalid_grant. Le point de terminaison de jeton OAuth renvoie des réponses de style OAuth { "error", "error_description" } plutôt que l'enveloppe d'erreur de l'API publique, et autorise 30 requêtes de jeton par adresse IP d'appelant et par minute.

N'authentifiez jamais les requêtes de gestion dans du code navigateur#

Ne placez jamais de clé API secrète, de jeton d'accès ou de jeton d'actualisation dans des composants client React, du JavaScript statique, du web mobile, Webflow, Framer, Wix ou du Liquid Shopify. Utilisez votre backend authentifié. L'intégration publique pour site web utilise un slug de site non secret et une liste d'origines autorisées, et non des identifiants de l'API de gestion.

Consultez Credentials and tokens, Scopes and errors et API quickstart.