Skip to main content

​
Security, credits & access

MCP tool calls are real actions on your organization — they spend credits and create assets exactly like the app and REST API. Treat an API key connected to an MCP client like any other production secret.
  • Credits. The nine media tools — generate_image, edit_image, img2img, create_variations, resize_image, upscale_image, remove_background, vectorize_image, and generate_video — draw from your organization’s shared credit pool at the app’s rates. Reads and model management are free. Check the balance any time with get_credit_balance.
  • Scopes. Every tool requires a scope. An API key or OAuth token only exposes the tools its scopes allow — narrow a key to exactly what an integration needs.
  • Revoking access. An admin revokes an API key in Settings → API Keys; revocation is terminal and takes effect on the very next call. For an OAuth connection, disconnect the connector in your client (Claude or ChatGPT connector settings); access tokens can also be revoked at Samsa’s OAuth revocation endpoint. A revoked credential stops working immediately.

​
Troubleshooting

A 401 is the server asking the client to (re)authenticate.
  • OAuth clients: disconnect the Samsa connector and reconnect to restart the sign-in. If consent never completes, tell us at support@samsa.ai.
  • API-key clients: confirm the header is exactly Authorization: Bearer samsa_sk_... and the key is valid — a missing, expired, or revoked key returns 401 invalid_api_key. Create a fresh key in Settings → API Keys if in doubt.
A credential always acts for one organization. An API key acts for the organization that owns it — to act for a different org, use a key created in that org. An OAuth connection acts for the account and organization you signed in with — reconnect to switch. Credits are drawn from, and assets appear in, that organization.
If the balance this connection can spend can’t cover a generation, the submit tool returns a structured error before any job runs — nothing is charged. Which code you get depends on the connection’s budget scope: insufficient_credits when the organization has no active teams, insufficient_team_credits when it is bound to a budgeted team, or insufficient_unallocated_credits when it is not. An operational failure inside the deduction falls back to the generic insufficient_credits whatever the regime — retry before buying credits — and a budget-exempt system organization stays under the org regime even with active teams. Check get_credit_balance — its available is the number a job’s cost must fit into, and its scope names the budget regime; under team or unallocated, compare plan_credits with scope.remaining to see which one is binding (under org, scope.remaining is null and only plan_credits can bind) — then top up, raise the team’s budget, or upgrade in the Samsa app. Reads are always free.
Three independent limits can slow a burst of calls:
  • Per-key request rate — 60 requests/minute; excess returns rate_limited.
  • Per-organization concurrency — at most 5 in-flight jobs at once; a sixth returns too_many_active_jobs. Let jobs finish (poll get_job_status) before submitting more.
  • MCP transport concurrency — a burst of simultaneous /mcp requests on a single worker can return a transient 429 concurrency_limit_exceeded with Retry-After: 1. Wait one second and retry.
See Rate limits for the full picture and back-off guidance.
Tools you can’t call are hidden or rejected because the connected credential lacks their scope. For example, generate_image needs images.generate. Edit the key’s scopes (or issue a new key) in Settings → API Keys, then reconnect.