Skip to main content

​
Sécurité, credits & accès

Les appels d’outils MCP sont des actions réelles sur ton organisation — ils dépensent des credits et créent des assets exactement comme l’app et l’API REST. Traite une API key connectée à un client MCP comme n’importe quel autre secret de production.
  • Credits. Les neuf outils média — generate_image, edit_image, img2img, create_variations, resize_image, upscale_image, remove_background, vectorize_image et generate_video — puisent dans le pool de credits partagé de ton organisation aux tarifs de l’app. Les lectures et la gestion de modèles sont gratuites. Vérifie le solde à tout moment avec get_credit_balance.
  • Scopes. Chaque outil requiert un scope. Une API key ou un token OAuth n’expose que les outils autorisés par ses scopes — restreins une clé exactement à ce dont une intégration a besoin.
  • Révoquer l’accès. Un admin révoque une API key dans Settings → API Keys ; la révocation est définitive et prend effet dès l’appel suivant. Pour une connexion OAuth, déconnecte le connecteur dans ton client (paramètres de connecteur de Claude ou ChatGPT) ; les access tokens peuvent aussi être révoqués au endpoint de révocation OAuth de Samsa. Un identifiant révoqué cesse de fonctionner immédiatement.

​
Dépannage

Un 401 est le server qui demande au client de (re)s’authentifier.
  • Clients OAuth : déconnecte le connecteur Samsa et reconnecte-toi pour relancer la connexion. Si le consentement ne se termine jamais, dis-le-nous à support@samsa.ai.
  • Clients API key : confirme que le header est exactement Authorization: Bearer samsa_sk_... et que la clé est valide — une clé manquante, expirée ou révoquée renvoie 401 invalid_api_key. Crée une clé fraîche dans Settings → API Keys en cas de doute.
Un identifiant agit toujours pour une organisation. Une API key agit pour l’organisation qui la possède — pour agir pour une autre org, utilise une clé créée dans cette org. Une connexion OAuth agit pour le compte et l’organisation avec lesquels tu t’es connecté — reconnecte-toi pour changer. Les credits sont prélevés sur cette organisation, et les assets y apparaissent.
Si le solde que cette connexion peut dépenser ne couvre pas une génération, l’outil de soumission renvoie une erreur structurée avant qu’aucun job ne tourne — rien n’est facturé. Le code obtenu dépend du scope de budget de la connexion : insufficient_credits quand l’organisation n’a aucune équipe active, insufficient_team_credits quand elle est affectée à une équipe budgétée, ou insufficient_unallocated_credits sinon. Une défaillance opérationnelle dans la déduction elle-même retombe sur le générique insufficient_credits quel que soit le régime — réessaie avant d’acheter des credits — et une organisation système exemptée du budgeting par équipe reste sous le régime org même avec des équipes actives. Vérifie get_credit_balance — son available est le nombre dans lequel le coût d’un job doit tenir, et son scope nomme le régime de budget ; sous team ou unallocated, compare plan_credits à scope.remaining pour voir lequel contraint (sous org, scope.remaining vaut null et seul plan_credits peut contraindre) —, puis recharge, augmente le budget de l’équipe ou fais évoluer ton plan dans l’app Samsa. Les lectures sont toujours gratuites.
Trois limites indépendantes peuvent ralentir un burst d’appels :
  • Rate de requêtes par clé — 60 requêtes/minute ; l’excès renvoie rate_limited.
  • Concurrence par organisation — au plus 5 jobs en cours à la fois ; un sixième renvoie too_many_active_jobs. Laisse les jobs finir (interroge get_job_status) avant d’en soumettre d’autres.
  • Concurrence du transport MCP — un burst de requêtes /mcp simultanées sur un même worker peut renvoyer un 429 concurrency_limit_exceeded transitoire avec Retry-After: 1. Attends une seconde et réessaie.
Voir Rate limits pour le tableau complet et les conseils de back-off.
Les outils que tu ne peux pas appeler sont masqués ou rejetés parce que l’identifiant connecté n’a pas leur scope. Par exemple, generate_image a besoin de images.generate. Modifie les scopes de la clé (ou émets une nouvelle clé) dans Settings → API Keys, puis reconnecte-toi.