> ## Documentation Index
> Fetch the complete documentation index at: https://docs.samsa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Security & troubleshooting

> Security, credits and access — plus what to do when a sign-in loops, a tool is missing, or a call is rejected.

## Security, credits & access

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

* **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](/guides/pricing) 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](/guides/authentication#scopes). 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

<AccordionGroup>
  <Accordion title="Repeated sign-in prompts or 401s" icon="triangle-exclamation">
    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](mailto: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`](/guides/errors#invalid_api_key). Create a
      fresh key in **Settings → API Keys** if in doubt.
  </Accordion>

  <Accordion title="Which organization am I acting as?" icon="building">
    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.
  </Accordion>

  <Accordion title="Tool call rejected — insufficient credits" icon="coins">
    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`](/guides/errors#insufficient_credits) when the organization has
    no active teams,
    [`insufficient_team_credits`](/guides/errors#insufficient_team_credits) when it is bound
    to a budgeted team, or
    [`insufficient_unallocated_credits`](/guides/errors#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](https://app.samsa.ai). Reads are always free.
  </Accordion>

  <Accordion title="Rate limited or too many jobs" icon="gauge-high">
    Three independent limits can slow a burst of calls:

    * **Per-key request rate** — 60 requests/minute; excess returns
      [`rate_limited`](/guides/errors#rate_limited).
    * **Per-organization concurrency** — at most 5 in-flight jobs at once; a sixth
      returns [`too_many_active_jobs`](/guides/errors#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](/guides/rate-limits) for the full picture and back-off
    guidance.
  </Accordion>

  <Accordion title="A tool is missing or says it lacks a scope" icon="lock">
    Tools you can't call are hidden or rejected because the connected credential
    lacks their [scope](/guides/authentication#scopes). For example,
    `generate_image` needs `images.generate`. Edit the key's scopes (or issue a new
    key) in **Settings → API Keys**, then reconnect.
  </Accordion>
</AccordionGroup>