# Authentification et idempotence

Identifiants, portées, Idempotency-Key et identifiants de requête pour chaque appel à l’API SciFig.

Source : https://scifig.ai/fr/docs/api/authentication

## Authentification Bearer

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.

## Portées

| Portée | Autorisations | Type de clé API |
| --- | --- | --- |
| figures:read | `GET /jobs`, `GET /jobs/{id}`, `GET /files/{file_id}`, `GET /credits` | Clé de lecture seule ; peut ne jamais expirer |
| figures:generate | Tout ce que permet `figures:read`, ainsi que tous les points d’accès `POST` | Clé de génération ; expire après 30 jours, 90 jours ou 1 an ; exige un abonnement actif ou un solde positif de crédits achetés en packs |

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.

## Idempotence

- 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](/fr/docs/api/files#upload).
- 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é.

## Clients OAuth

- 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.

## Identifiants de requête

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.