Skip to main content

​
Sicherheit, Credits & Zugriff

MCP-Tool-Aufrufe sind echte Aktionen auf deiner Organisation — sie geben Credits aus und erstellen Assets genau wie App und REST API. Behandle einen mit einem MCP client verbundenen API key wie jedes andere Produktions-Secret.
  • Credits. Die neun Medien-Tools — generate_image, edit_image, img2img, create_variations, resize_image, upscale_image, remove_background, vectorize_image und generate_video — ziehen aus dem gemeinsamen Credit-Pool deiner Organisation zu den Raten der App. Reads und Modellverwaltung sind kostenlos. Prüfe das Guthaben jederzeit mit get_credit_balance.
  • Scopes. Jedes Tool erfordert einen Scope. Ein API key oder OAuth-Token stellt nur die Tools bereit, die seine Scopes erlauben — schränke einen Key auf genau das ein, was eine Integration braucht.
  • Zugriff widerrufen. Ein Admin widerruft einen API key in Settings → API Keys; der Widerruf ist terminal und wird beim allernächsten Aufruf wirksam. Für eine OAuth-Verbindung trenne den Connector in deinem Client (Claude- oder ChatGPT-Connector-Einstellungen); Access-Tokens können auch an Samsas OAuth-Revocation-Endpoint widerrufen werden. Ein widerrufenes Credential funktioniert sofort nicht mehr.

​
Fehlerbehebung

Ein 401 ist der Server, der den Client bittet, sich (erneut) zu authentifizieren.
  • OAuth-Clients: trenne den Samsa-Connector und verbinde ihn erneut, um den Login neu zu starten. Wenn der Consent nie abschließt, sag uns unter support@samsa.ai Bescheid.
  • API-key-Clients: bestätige, dass der Header exakt Authorization: Bearer samsa_sk_... lautet und der Key gültig ist — ein fehlender, abgelaufener oder widerrufener Key gibt 401 invalid_api_key zurück. Erstelle im Zweifel einen frischen Key in Settings → API Keys.
Ein Credential handelt immer für eine Organisation. Ein API key handelt für die Organisation, die ihn besitzt — um für eine andere Org zu handeln, verwende einen Key, der in dieser Org erstellt wurde. Eine OAuth-Verbindung handelt für das Konto und die Organisation, mit denen du dich angemeldet hast — verbinde dich neu, um zu wechseln. Credits werden aus dieser Organisation gezogen, und Assets erscheinen in ihr.
Wenn der Stand, den diese Verbindung ausgeben kann, eine Generierung nicht abdeckt, gibt das Submit-Tool einen strukturierten Fehler zurück, bevor irgendein Job läuft — es wird nichts berechnet. Welchen Code du bekommst, hängt vom Budget-Scope der Verbindung ab: insufficient_credits, wenn die Organisation keine aktiven Teams hat, insufficient_team_credits, wenn sie einem Team mit Budget zugewiesen ist, sonst insufficient_unallocated_credits. Ein operativer Fehler in der Abbuchung selbst fällt unabhängig vom Regime auf das generische insufficient_credits zurück — wiederhole, bevor du Credits kaufst — und eine vom Team-Budgeting ausgenommene System-Organisation bleibt auch mit aktiven Teams im org-Regime. Prüfe get_credit_balance — dessen available ist die Zahl, in die die Kosten eines Jobs passen müssen, und dessen scope nennt das Budget-Regime; unter team oder unallocated vergleichst du plan_credits mit scope.remaining, um zu sehen, was begrenzt (unter org ist scope.remaining null und nur plan_credits kann begrenzen) —, dann lade auf, erhöhe das Team-Budget oder upgrade in der Samsa-App. Reads sind immer kostenlos.
Drei unabhängige Limits können einen Ansturm von Aufrufen bremsen:
  • Request-Rate pro Key — 60 Requests/Minute; ein Überschuss gibt rate_limited zurück.
  • Concurrency pro Organisation — höchstens 5 gleichzeitige Jobs; ein sechster gibt too_many_active_jobs zurück. Lass Jobs fertig werden (frage get_job_status ab), bevor du weitere einreichst.
  • MCP-Transport-Concurrency — ein Ansturm gleichzeitiger /mcp-Requests auf einem einzelnen Worker kann einen transienten 429 concurrency_limit_exceeded mit Retry-After: 1 zurückgeben. Warte eine Sekunde und versuche es erneut.
Siehe Rate Limits für das vollständige Bild und Hinweise zum Back-off.
Tools, die du nicht aufrufen kannst, sind versteckt oder abgelehnt, weil dem verbundenen Credential ihr Scope fehlt. Zum Beispiel braucht generate_image images.generate. Bearbeite die Scopes des Keys (oder erstelle einen neuen Key) in Settings → API Keys und verbinde dich dann neu.