Risorse · Autenticazione

Documentazione su Autenticazione e Ambiti

Guida pronta per la produzione all'autenticazione JWT/sessione, all'autenticazione con API key, agli header di ambito, al contesto dello spazio di lavoro e alle regole di validazione.

Torna alla Documentazione Vai ai metodi di autenticazione

Metodi di autenticazione

Autenticazione JWT/sessione per richieste nel contesto utente.
Autenticazione con API key per comunicazioni service-to-service e integrazioni controllate.

Intestazioni richieste

Authorization: Bearer [jwt_token] O X-API-Key: [api_key]Content-Type: application/jsonX-Scope-Type: personal | workspaceX-Workspace-ID: richiesto solo nell'ambito dello spazio di lavoro

Modello di ambiti

L'ambito personale viene eseguito nel contesto dell'utente autenticato.
L'ambito dello spazio di lavoro viene eseguito all'interno di uno specifico spazio di lavoro con controlli basati sui ruoli.

Regole di validazione

Se l'ambito è personale, X-Workspace-ID non deve essere fornito.
Se l'ambito è dello spazio di lavoro, X-Workspace-ID è obbligatorio.
Header di ambito non validi o in conflitto restituiscono 422.

Esempio di autenticazione JWT

bash

curl -X POST "/api/v1/chat/completions" \
  -H "Authorization: Bearer [jwt_token]" \
  -H "Content-Type: application/json" \
  -H "X-Scope-Type: personal" \
  -d '{
    "message":"Hello from JWT auth",
    "stream":false
  }'

Esempio di autenticazione con API key

bash

curl -X POST "/api/v1/chat/completions" \
  -H "X-API-Key: [api_key]" \
  -H "Content-Type: application/json" \
  -H "X-Scope-Type: workspace" \
  -H "X-Workspace-ID: [workspace_uuid]" \
  -d '{
    "message":"Hello from API key auth",
    "stream":false
  }'

Ambito dello spazio di lavoro

json

{
  "headers": {
    "X-Scope-Type": "workspace",
    "X-Workspace-ID": "[workspace_uuid]"
  },
  "note": "Workspace scope requires workspace id."
}

Ambito personale

json

{
  "headers": {
    "X-Scope-Type": "personal"
  },
  "note": "Personal scope must not include workspace id."
}

Modelli di errore

401

Autenticazione mancante, scaduta o non valida.

403

Ambito non consentito o restrizione di ruolo nello spazio di lavoro.

422

La validazione di header/contesto è fallita.

429

Limite di richieste superato per il contesto di autenticazione corrente.