Autenticazione

Ogni richiesta alla Samsa API è autenticata con una API key di organizzazione. Le chiavi hanno degli scope, vengono mostrate una sola volta e agiscono per l’organizzazione che le possiede — i credits vengono prelevati dal pool di quell’organizzazione e gli asset generati appaiono nell’app sotto l’account dell’admin che ha creato la chiave.

Stai connettendo Samsa a un client MCP (Claude, ChatGPT, Claude Code, Cursor…)? L’ MCP server usa queste stesse API key per i client headless e l’accesso OAuth 2.1 per quelli interattivi — gli scope qui sotto si applicano agli strumenti MCP in modo identico.

Come funzionano le chiavi

Di proprietà dell’organizzazione. Una chiave appartiene a un’organizzazione, non a una persona. Chiunque possieda la chiave agisce per quell’organizzazione.
Create da un admin. Solo un admin dell’organizzazione (OWNER o ADMIN) può creare o revocare chiavi, nella scheda Settings → API Keys dell’app.
Con scope. Ogni chiave porta un insieme di scope che determinano quali endpoint può chiamare. Le chiavi vengono create con tutti gli scope per impostazione predefinita; restringili per corrispondere a ciò di cui l’integrazione ha bisogno.
Mostrate una sola volta. Il segreto completo viene visualizzato esattamente una volta, alla creazione.

Samsa memorizza solo un hash SHA-256 di ogni chiave, mai il testo in chiaro. Ecco perché una chiave non può mai essere mostrata di nuovo o recuperata — non c’è nulla da cui recuperare. Se perdi una chiave, revocala e creane una nuova.

L’header `Authorization`

Invia la tua chiave come Bearer token in ogni richiesta:

Authorization: Bearer samsa_sk_your_key_here

curl https://api.samsa.ai/public/v1/me \
  -H "Authorization: Bearer $SAMSA_API_KEY"

import os
import requests

BASE_URL = "https://api.samsa.ai/public/v1"
headers = {"Authorization": f"Bearer {os.environ['SAMSA_API_KEY']}"}

resp = requests.get(f"{BASE_URL}/me", headers=headers)
resp.raise_for_status()
print(resp.json())

const BASE_URL = "https://api.samsa.ai/public/v1";
const headers = { Authorization: `Bearer ${process.env.SAMSA_API_KEY}` };

const resp = await fetch(`${BASE_URL}/me`, { headers });
if (!resp.ok) throw new Error(`GET /me failed: ${resp.status}`);
console.log(await resp.json());

Usa GET /me per confermare che una chiave funzioni — restituisce l’organizzazione della chiave, i suoi metadati sicuri (prefisso, scope, scadenza) e il saldo credits disponibile dell’organizzazione, ma mai il segreto.

Scope

Gli scope seguono la forma <resource>.<verb>. Una richiesta a un endpoint il cui scope manca alla chiave fallisce con 403 missing_scope.

Scope	Endpoint sbloccati
`images.generate`	`POST /images/generations`, `GET /images/generations/{id}`
`images.edit`	`POST /images/edits`, `GET /images/edits/{id}`
`videos.generate`	`POST /videos/generations`, `GET /videos/generations/{id}`, `GET /videos/models`
`models.read`	`GET /models`, `GET /models/{id}`, `GET /models/{id}/status`
`models.write`	`POST /models`, `POST /models/prepare`, `POST /models/{id}/complete`, `PATCH /models/{id}`, `DELETE /models/{id}`
`usage.read`	`GET /credits`, `GET /usage`

GET /me necessita di qualsiasi chiave valida — non richiede alcuno scope specifico. Le nuove funzionalità aggiungono nuove stringhe di scope; le chiavi esistenti non le ereditano mai automaticamente, quindi un admin modifica gli scope della chiave o emette una nuova chiave per concedere l’accesso.

Quando l’autenticazione fallisce

I fallimenti di autenticazione e autorizzazione restituiscono l’ envelope di errore standard. Una chiave mancante, malformata, sconosciuta, scaduta o revocata — oppure una chiave il cui creatore non è più membro dell’organizzazione — restituisce 401 invalid_api_key:

401 Unauthorized

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid, expired, or revoked.",
    "request_id": "req_8f14e45fceea167a"
  }
}

Una chiave valida a cui manca lo scope dell’endpoint restituisce 403 missing_scope, nominando lo scope richiesto:

403 Forbidden

{
  "error": {
    "type": "permission_error",
    "code": "missing_scope",
    "message": "The API key is missing the required scope: images.generate.",
    "request_id": "req_1c9a3b7d2e5f4a80",
    "param": "scope"
  }
}

Le chiavi scadute e quelle sconosciute restituiscono entrambe 401 invalid_api_key — deliberatamente indistinguibili, così un estraneo non può sondare quali chiavi siano esistite.

Best practice di sicurezza

Conserva le chiavi in variabili d'ambiente

Tieni le chiavi fuori dal controllo di versione. Caricale da una variabile d’ambiente o da un secrets manager — non scriverle mai hard-coded.

export SAMSA_API_KEY="samsa_sk_..."

Non esporre mai le chiavi lato client

La Samsa API è server-side first — il CORS è deliberatamente restrittivo e le chiamate dal browser da origini arbitrarie non sono supportate. Una chiave nel codice front-end o in un’app mobile è una chiave trapelata. Chiama sempre l’API dal tuo backend.

Ruota tramite revoca + creazione

Non esiste una rotazione in-place. Per ruotare, crea una nuova chiave, distribuiscila, poi revoca quella vecchia. La revoca è definitiva e ha effetto alla richiesta immediatamente successiva.

Imposta una scadenza per le integrazioni di breve durata

Le chiavi possono essere create con una scadenza facoltativa. Una chiave scaduta fallisce esattamente come una sconosciuta (401 invalid_api_key). Usa la scadenza per integrazioni temporanee, trial e collaboratori esterni.

Ruotare una chiave

Crea una nuova chiave in Settings → API Keys e copiala.
Distribuisci la nuova chiave alla tua integrazione.
Revoca la vecchia chiave. La revoca è immediata e non può essere annullata.

Formato della chiave

Una chiave ha questo aspetto:

samsa_sk_gK3n8vQ1xY7bT2mW9cR4jL6hF0dS5pZaU8eN1oI3rAb
└───┬───┘└──────────────────┬─────────────────────┘
 prefix           43 random base62 characters

Il corpo di samsa_sk_ è composto da 43 caratteri base62 che codificano 256 bit di casualità. Nell’app, le chiavi vengono visualizzate come samsa_sk_gK3n…3rAb (un prefix stabile più gli ultimi quattro caratteri) così puoi identificare una chiave senza esporla.

Il prefisso costante samsa_sk_ permette agli scanner di segreti (GitHub secret scanning, hook pre-commit, controlli CI) di rilevare una chiave Samsa committata per errore. Abilita il secret scanning sui tuoi repository così una chiave trapelata viene intercettata prima che venga distribuita.

Per iniziare

API

Verifica dei contenuti

Come funzionano le chiavi

L’header `Authorization`

Scope

Quando l’autenticazione fallisce

Best practice di sicurezza

Ruotare una chiave

Formato della chiave

​Come funzionano le chiavi

​L’header Authorization

​Scope

​Quando l’autenticazione fallisce

​Best practice di sicurezza

​Ruotare una chiave

​Formato della chiave

Come funzionano le chiavi

L’header `Authorization`

Scope

Quando l’autenticazione fallisce

Best practice di sicurezza

Ruotare una chiave

Formato della chiave