Autenticazione

Contit supporta più metodi di autenticazione a seconda del caso d'uso.

Metodi disponibili

Metodo	Caso d'uso	Header
Client Credentials (OAuth2)	Server-to-server, operazioni di scrittura	Authorization: Bearer {token}
API Key	Accesso pubblico in lettura, integrazioni semplici	X-Api-Key: {key} oppure ?api_key={key}
Personal Access Token (PAT)	Agenti AI / server MCP, token per-utente	Authorization: Bearer ctpat_...
Authorization Code + PKCE	Applicazioni utente (login da browser)	Authorization: Bearer {token}
Refresh Token	Sessioni di lunga durata	Rinnovo su /connect/token

---

Client Credentials (raccomandato per server-side)

1. Ottieni un access token

curl -X POST https://idp.contit.cloud/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=TUO_CLIENT_ID&client_secret=TUO_CLIENT_SECRET"

Risposta:

{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600
}

2. Usa il token

curl https://api.contit.cloud/contents/mioContentType \
  -H "Authorization: Bearer eyJhbGci..."

Durata del token: 1 ora. Usa il grant refresh_token per rinnovarlo senza riautenticarsi.

---

API Key

Le API Key sono adatte per accesso pubblico in lettura (es. frontend, API pubbliche).

# Via header
curl https://api.contit.cloud/contents/mioContentType \
  -H "X-Api-Key: LA_TUA_API_KEY"

# Via query parameter
curl "https://api.contit.cloud/contents/mioContentType?api_key=LA_TUA_API_KEY"

---

Personal Access Token (PAT)

I Personal Access Token sono legati a un singolo utente e sono pensati per configurare agenti AI e il server MCP (Claude Code/Desktop o altri strumenti). A differenza delle Chiavi API (legate a un client del workspace), un PAT agisce a nome dell'utente che lo ha generato.

1. Genera il token

Dalla console Contit: Impostazioni → Sviluppatore → Personal Access Token → Aggiungi. Scegli nome, scadenza, permessi (lettura / lettura-scrittura) ed eventuali permessi per tipo di contenuto. Il token viene mostrato una sola volta in fase di creazione: copialo subito.

Un PAT ha il formato ctpat_....

2. Usa il token direttamente

Il PAT può essere usato come Bearer su tutte le API: viene risolto automaticamente lato server.

curl https://api.contit.cloud/contents/mioContentType \
  -H "Authorization: Bearer ctpat_xxxxxxxx"

3. Scambio esplicito con un JWT (opzionale)

Se preferisci ottenere un access token JWT a partire dal PAT, usa il grant pat:

curl -X POST https://idp.contit.cloud/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=pat&pat=ctpat_xxxxxxxx"

Il token risultante contiene il claim email dell'utente, contit:workspaceId e i contit:permissions del PAT.

---

Introspection (validazione centralizzata)

L'endpoint POST /connect/introspect (RFC 7662) permette alle app riservate di validare un PAT in modo centralizzato, senza re-implementare la verifica. La chiamata è autenticata con le credenziali dell'app installata.

curl -X POST https://idp.contit.cloud/connect/introspect \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=ctpat_xxxxxxxx&client_id=APP_CLIENT_ID&client_secret=APP_CLIENT_SECRET"

Risposta (token valido):

{
  "active": true,
  "token_type": "pat",
  "sub": "user-id",
  "email": "[email protected]",
  "name": "Mario Rossi",
  "contit:workspaceId": "ws-id",
  "contit:permissions": ["read", "write"],
  "exp": 1750000000
}

Per un token non valido o scaduto la risposta è { "active": false }.

Nell'SDK .NET puoi usare la classe ContitTokenValidator:

var validator = new ContitTokenValidator(appClientId, appClientSecret);
var info = await validator.ValidateAsync(incomingToken);
if (info.Active)
{
    // info.UserId, info.WorkspaceId, info.CanRead, info.CanWrite
}

---

Claims personalizzati

Tutti i token rilasciati da Contit contengono claims personalizzati:

Claim	Descrizione
contit:workspaceId	ID del workspace associato al client
contit:permissions	Lista separata da virgole: read, write, app.read, app.user
contit:clientLogActive	Indica se il logging delle richieste è attivo
contit:ctPermissions	Permessi per tipo di contenuto (JSON, opzionale)

---

Policy di autorizzazione

Policy	Permesso richiesto	Usata per
ReadAccess	read	Operazioni GET e POST (ricerca)
WriteAccess	write	Operazioni PUT e DELETE
App.ReadAccess	app.read	Endpoint impostazioni app
App.UserAccess	app.user	Operazioni app cross-workspace

---

Permessi per tipo di contenuto

Ogni client puo' essere configurato per limitare l'accesso a specifici tipi di contenuto, con permessi di lettura e scrittura indipendenti.

Comportamento

• Nessuna configurazione (default): il client ha accesso a tutti i tipi di contenuto, inclusi quelli creati in futuro. Lettura e scrittura sono controllati dal flag globale Readonly.
• Permessi configurati: il client puo' accedere solo ai tipi di contenuto elencati, con lettura e scrittura specificati per ognuno. I tipi di contenuto creati dopo la configurazione non saranno accessibili finche' non vengono aggiunti alla lista.

Configurazione

Nella sezione Chiavi API delle impostazioni del workspace, seleziona un client e attiva l'opzione "Limita accesso per tipo di contenuto". Per ogni tipo di contenuto puoi abilitare:

Permesso	Descrizione
Lettura	Il client puo' cercare e recuperare contenuti di questo tipo
Scrittura	Il client puo' creare e aggiornare contenuti di questo tipo
Eliminazione	Il client puo' eliminare contenuti di questo tipo

I tre permessi sono indipendenti: e' possibile ad esempio concedere la scrittura senza l'eliminazione.

Esempio

Un client configurato con:

• articoli: lettura + scrittura + eliminazione
• categorie: solo lettura
• prodotti: lettura + scrittura (senza eliminazione)

Potra' gestire completamente gli articoli, solo consultare le categorie, e creare/modificare prodotti senza poterli eliminare. Non avra' accesso ad altri tipi di contenuto (es. pagine).