Skip to main content

​
Sicurezza, credits e accesso

Le chiamate agli strumenti MCP sono azioni reali sulla tua organizzazione — spendono credits e creano asset esattamente come l’app e la REST API. Tratta una API key connessa a un client MCP come qualsiasi altro segreto di produzione.
  • Credits. I nove strumenti multimediali — generate_image, edit_image, img2img, create_variations, resize_image, upscale_image, remove_background, vectorize_image e generate_video — prelevano dal pool di credits condiviso della tua organizzazione alle tariffe dell’app. Le letture e la gestione dei modelli sono gratuite. Controlla il saldo in qualsiasi momento con get_credit_balance.
  • Scope. Ogni strumento richiede uno scope. Una API key o un token OAuth espone solo gli strumenti consentiti dai suoi scope — restringi una chiave esattamente a ciò di cui un’integrazione ha bisogno.
  • Revoca dell’accesso. Un admin revoca una API key in Settings → API Keys; la revoca è definitiva e ha effetto alla chiamata immediatamente successiva. Per una connessione OAuth, disconnetti il connector nel tuo client (impostazioni dei connector di Claude o ChatGPT); gli access token possono anche essere revocati all’endpoint di revoca OAuth di Samsa. Una credenziale revocata smette di funzionare immediatamente.

​
Risoluzione dei problemi

Un 401 è il server che chiede al client di (ri)autenticarsi.
  • Client OAuth: disconnetti il connector Samsa e riconnettiti per riavviare l’accesso. Se il consenso non si completa mai, faccelo sapere a support@samsa.ai.
  • Client con API key: verifica che l’header sia esattamente Authorization: Bearer samsa_sk_... e che la chiave sia valida — una chiave mancante, scaduta o revocata restituisce 401 invalid_api_key. In caso di dubbio, crea una nuova chiave in Settings → API Keys.
Una credenziale agisce sempre per una sola organizzazione. Una API key agisce per l’organizzazione che la possiede — per agire per un’altra org, usa una chiave creata in quell’org. Una connessione OAuth agisce per l’account e l’organizzazione con cui hai effettuato l’accesso — riconnettiti per cambiare. I credits vengono prelevati da, e gli asset appaiono in, quell’organizzazione.
Se il saldo che questa connessione può spendere non copre una generazione, lo strumento di invio restituisce un errore strutturato prima che qualsiasi job venga eseguito — nulla viene addebitato. Il codice che ricevi dipende dallo scope di budget della connessione: insufficient_credits quando l’organizzazione non ha team attivi, insufficient_team_credits quando è assegnata a un team con budget, altrimenti insufficient_unallocated_credits. Un guasto operativo nella detrazione stessa ricade sul generico insufficient_credits qualunque sia il regime — riprova prima di acquistare credits — e un’organizzazione di sistema esente dal budgeting per team resta nel regime org anche con team attivi. Controlla get_credit_balance — il suo available è il numero in cui deve rientrare il costo di un job, e il suo scope indica il regime di budget; sotto team o unallocated, confronta plan_credits con scope.remaining per vedere quale dei due vincola (sotto org, scope.remaining è null e solo plan_credits può vincolare) —, poi ricarica, aumenta il budget del team o esegui l’upgrade nell’app Samsa. Le letture sono sempre gratuite.
Tre limiti indipendenti possono rallentare una raffica di chiamate:
  • Rate di richieste per chiave — 60 richieste/minuto; l’eccesso restituisce rate_limited.
  • Concorrenza per organizzazione — al massimo 5 job in corso alla volta; un sesto restituisce too_many_active_jobs. Lascia finire i job (interroga get_job_status) prima di inviarne altri.
  • Concorrenza del transport MCP — una raffica di richieste /mcp simultanee su un singolo worker può restituire un transitorio 429 concurrency_limit_exceeded con Retry-After: 1. Aspetta un secondo e riprova.
Consulta Rate limits per il quadro completo e le indicazioni sul back-off.
Gli strumenti che non puoi chiamare sono nascosti o rifiutati perché la credenziale connessa non ha il loro scope. Per esempio, generate_image necessita di images.generate. Modifica gli scope della chiave (o emetti una nuova chiave) in Settings → API Keys, poi riconnettiti.