Authentification et idempotence

Envoyez Authorization: Bearer <credential> avec chaque requête, sauf GET /pricing, GET /openapi.json et GET /openapi.yaml. Les identifiants transmis dans les paramètres de requête ou d’autres en-têtes sont ignorés.

Les identifiants utilisent l’authentification Bearer ; les identifiants liés à DPoP ne sont pas pris en charge.

• Les clés API commencent par sk_live_. Créez-les dans Paramètres → Développeur ; la clé n’est affichée qu’une fois. Conservez-la sur un serveur et ne l’intégrez jamais à une application de navigateur ou mobile. Nous vous envoyons un e-mail 7 jours avant son expiration.
• Les jetons d’accès OAuth commencent par sf_at_. Les clients MCP les reçoivent une fois que vous les avez autorisés ; vous pouvez déconnecter un client dans Paramètres → Développeur → Applications connectées.
• Un identifiant manquant, invalide, expiré ou révoqué renvoie 401 UNAUTHORIZED. Un compte qui ne peut pas utiliser l’API, par exemple en cours de suppression, renvoie 401 ACCOUNT_UNAVAILABLE.
• Révoquer une clé empêche les nouvelles requêtes avec cette clé ; les tâches qu’elle a déjà créées continuent et restent consultables avec d’autres identifiants du même compte.

Une requête en dehors de la portée des identifiants renvoie 403 SCOPE_DENIED. Utilisez une clé distincte par application et par environnement afin de pouvoir en révoquer une sans affecter les autres.

• Chaque requête de création (POST /images/*, /charts/*, /flowcharts/*) exige un en-tête Idempotency-Key contenant 1 à 255 caractères ASCII visibles. Un UUID aléatoire par requête est le choix le plus simple. Les importations vers POST /files peuvent aussi en envoyer un ; voir fichiers.
• La même clé avec le même corps renvoie la même tâche et ne réserve jamais de crédits supplémentaires. Pour les importations de graphiques, les octets du fichier de données font partie du corps.
• La même clé avec un corps différent renvoie 409 IDEMPOTENCY_CONFLICT. Des requêtes simultanées avec la même clé ne créent jamais deux tâches : chacune renvoie la même tâche, ou 409 IDEMPOTENCY_IN_PROGRESS avec Retry-After: 1 tant que la première est encore en cours d’admission.
• Réessayez avec la même clé après un dépassement de délai, une erreur réseau, un 429 ou un 503 : c’est le seul moyen de garantir qu’une tâche n’est pas créée deux fois.
• Une fois la tâche créée, une erreur permettant une nouvelle tentative (429, 503, 409 IDEMPOTENCY_IN_PROGRESS) ou 500 INTERNAL_ERROR contient details.job_id. Réessayez avec la même clé ou interrogez GET /jobs/{job_id} ; ne passez pas à une nouvelle clé, qui créerait et facturerait une seconde tâche. Une tâche acceptée mais impossible à relire reçoit une réponse 202 avec le statut queued.
• Une requête refusée, par exemple 402 INSUFFICIENT_CREDITS, conserve cette réponse pour sa clé. Après un rechargement ou un changement d’offre, renvoyez-la avec une nouvelle clé.

• Les clients MCP utilisent OAuth 2.1 avec PKCE. Les jetons d’accès (sf_at_…) sont valables 1 heure. Un client demandant la portée offline_access reçoit aussi un jeton de renouvellement (sf_rt_…) valable 30 jours et reste connecté jusqu’à ce que vous le déconnectiez ; sans offline_access, vous devez vous reconnecter lorsque le jeton d’accès expire.
• Les jetons de renouvellement sont renouvelés par rotation : chaque renouvellement en renvoie un nouveau. Présenter un jeton déjà utilisé est considéré comme une réutilisation et révoque les jetons émis à partir de celui-ci ; le client doit alors se reconnecter.
• L’enregistrement dynamique des clients accepte un corps de 16 KB au maximum, avec des limites sur la longueur des champs et le nombre d’URI de redirection. L’authentification au point d’accès des jetons est none pour les clients publics avec PKCE, ou client_secret_basic.
• Un client enregistré mais jamais autorisé est supprimé après 24 heures.
• Une demande d’autorisation avec prompt=login ou max_age exige une nouvelle connexion. Si vous êtes déjà connecté, SciFig vous demande confirmation avant de vous déconnecter puis de vous reconnecter.
• Les limites des identifiants OAuth sont comptabilisées par client et par compte : les autres utilisateurs du même assistant ne consomment pas vos limites.

Chaque réponse contient X-Request-Id ; les corps d’erreur le répètent dans error.request_id. Il identifie la requête dans nos journaux sans exposer d’autres informations : vous pouvez donc le journaliser et le communiquer au support.