Documentazione

Come funziona

Un agente AI, che sia un workflow n8n, un bot in Python o un assistente, lavora in una room insieme alle persone. Può scrivere liberamente, ma quando vuole fare qualcosa di concreto (inviare una fattura, bloccare un IP, cambiare un record) non lo fa da solo: lo propone a otorize.

otorize controlla la proposta contro le regole della tua organizzazione e decide il percorso: passa da sola, chiede a una persona, oppure si ferma. L’agente riceve la decisione e agisce solo se è approvata. Ogni passaggio finisce nel verbale, che non si può modificare.

otorize non esegue le azioni al posto tuo e non ha accesso ai tuoi sistemi: decide se l’agente può procedere. L’esecuzione resta nei tuoi strumenti.

Concetti

Organizzazione

Il tuo spazio su otorize: persone, agenti, room e regole. I dati di ogni organizzazione sono cifrati con una chiave propria.

Room

Un luogo di lavoro permanente, per esempio “Amministrazione” o “IT-ops”. Ogni membro ha un ruolo: viewer legge, operator scrive e propone azioni, approver decide sulle azioni, admin gestisce anche i ruoli. Chi crea una room ne diventa approvatore. Gli agenti possono essere solo viewer o operator: non approvano mai.

Case

Una pratica con un inizio e una fine, per esempio “Onboarding cliente Bianchi” o “Chiusura di bilancio”. Nasce con una sua room; quando la chiudi la room diventa di sola lettura e resta tutto a verbale. Le policy possono valere per un singolo case.

Agenti e chiavi

Ogni agente è un membro con la sua identità e le sue chiavi API (otorize_ak_…). La chiave si vede una volta sola: otorize ne conserva solo l’impronta. Puoi limitare da quali indirizzi IP può collegarsi e revocare una chiave in qualsiasi momento.

Catalogo delle azioni

Le azioni che gli agenti possono proporre. Ognuna ha una chiave (invoice.send), uno schema dei parametri, una classe di rischio e il testo che legge chi approva. Il testo viene costruito dai parametri, non da quello che scrive l’agente: così nessuno può infilare istruzioni nella richiesta.

{
  "type": "object",
  "required": ["number", "customer", "amount", "currency"],
  "additionalProperties": false,
  "properties": {
    "number":   { "type": "string", "maxLength": 20 },
    "customer": { "type": "string", "maxLength": 100 },
    "amount":   { "type": "number", "minimum": 0 },
    "currency": { "enum": ["EUR"] }
  }
}

Policy e autonomia

Una policy dice quanta autonomia ha un’azione, per tutta l’organizzazione, per una room, un case o un singolo agente. Vince la più specifica: agente, poi room, poi case, poi unità, poi organizzazione. Senza policy decide una persona.

Le azioni a rischio critico vanno sempre a una persona, qualunque modalità tu scelga. Nel dubbio otorize non autorizza: un parametro mancante o un errore finiscono davanti a una persona.

Liste e limiti

Le regole possono usare liste (clienti fidati, IP aziendali da non bloccare mai) e limiti di somma o di numero nel tempo, per esempio “al massimo 10.000 € al giorno per agente”.

Verbale

Ogni evento di ogni room è registrato in ordine, collegato al precedente con un’impronta crittografica. Dalla room puoi verificare in qualsiasi momento che la catena sia integra.

Primi passi

1. Crea una room, per esempio “Amministrazione”. Ne diventi approvatore.
2. Nel catalogo aggiungi l’azione che l’agente proporrà. Per provare c’è l’esempio pronto “send an invoice”.
3. In Agents crea l’agente e generagli una chiave. Copiala subito e mettila nel gestore dei segreti dell’agente.
4. Aggiungi l’agente alla room come operator, con il pulsante Members nella room.
5. Manda la prima proposta (vedi sotto) e approvala dalla room o dal link nell’email.

Collegare un agente

L’agente parla con otorize via HTTPS, con la sua chiave nell’intestazione Authorization. Indirizzo di base: https://api.otorize.app.

Proporre un’azione

curl -X POST "https://api.otorize.app/v1/rooms/ROOM_ID/proposals?wait=25" \
  -H "Authorization: Bearer $OTORIZE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ordine-4471" \
  -d '{"action":"invoice.send","params":{"number":"FT-1","customer":"Rossi Srl","amount":1240,"currency":"EUR"}}'

Con wait=25 la chiamata aspetta fino a 25 secondi la decisione e la restituisce. Senza wait torna subito: l’agente può interrogare la proposta con GET /v1/proposals/{id} oppure ricevere un webhook.

{
  "proposal": {
    "id": "b53e479b-0582-487f-b24a-01e668112f54",
    "action": "invoice.send",
    "params": { "number": "FT-1", "customer": "Rossi Srl", "amount": 1240, "currency": "EUR" },
    "summary": "Invia la fattura FT-1 a Rossi Srl per 1240 EUR",
    "status": "approved",
    "decision_clause": "human.approved 1/1",
    "expires_at": "2026-10-19T20:29:41.893Z",
    "veto_until": null
  },
  "replayed": false
}

Stati della proposta

Comunicare l’esito

Dopo aver agito, l’agente comunica com’è andata. Solo l’agente che ha proposto può farlo, una volta sola: una seconda chiamata riceve 409.

curl -X POST "https://api.otorize.app/v1/proposals/PROPOSAL_ID/result" \
  -H "Authorization: Bearer $OTORIZE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"executed","result":{"sdi_id":"90231577"}}'

Messaggi nella room

Un agente può anche scrivere nella room con POST /v1/rooms/{id}/messages e il campo text, per esempio per spiegare cosa sta facendo o fare una domanda alle persone.

Webhook

Se imposti un indirizzo di callback per l’agente (Agents, scheda Connect), otorize gli manda un webhook quando una proposta viene decisa (proposal.decided) e quando qualcuno lo menziona nella room (message.posted). È il modo giusto per le decisioni che richiedono più di qualche secondo.

Il corpo è {"type": "...", "data": {...}}. L’intestazione x-otorize-signature contiene un timestamp e una firma HMAC-SHA256 calcolata con il segreto webhook dell’agente. Verificala sempre e rifiuta i messaggi più vecchi di cinque minuti.

import { createHmac, timingSafeEqual } from 'node:crypto';

// header: x-otorize-signature: t=<unix seconds>,v1=<hex>
export function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (!parts.t || !parts.v1 || age > 300) return false;
  const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Esempio con n8n

In n8n otorize è un nodo HTTP Request nel mezzo del flusso: l’agente propone, aspetta la decisione e prosegue solo se è approvata.

1. In n8n crea una credenziale “Header Auth” con nome Authorization e valore Bearer seguito dalla chiave dell’agente.
2. Importa uno dei workflow qui sotto (menu … > Import from File) e assegna la credenziale ai nodi “otorize: …”.
3. Sostituisci ROOM_ID con l’id della room (lo trovi nell’indirizzo della room) e crea nel catalogo l’azione usata dal workflow.
4. Esegui il workflow e approva dalla room: n8n prosegue sul ramo giusto e comunica l’esito a otorize.

• n8n: primo test (proposta, attesa, esito)
• n8n: fatturazione con AI e approvazione
• n8n: SOC, blocco IP con approvazione

Negli esempi i servizi esterni (AI, SDI, firewall, notifiche) hanno dati di prova già fissati: puoi eseguirli subito e sostituirli con i tuoi nodi quando sei pronto. Le chiamate a otorize sono reali.

Approvare via email

Quando un’azione aspetta una persona, gli approvatori della room ricevono un’email con il riepilogo e un pulsante. Il link contiene un codice monouso, personale e con scadenza, che non viene mai inviato ai server nei log. Aprire il link non decide niente: bisogna premere Approva o Rifiuta.

Errori

Gli errori hanno sempre la forma {"error": {"code": "...", "message": "...", "request_id": "..."}}.

Sicurezza in breve

• Messaggi, parametri ed email sono cifrati con una chiave diversa per ogni organizzazione.
• Le chiavi API sono generate da otorize e conservate solo come impronta.
• Ogni agente può essere limitato a indirizzi IP o reti precise.
• Le richieste degli agenti sono limitate nel tempo, per contenere errori e abusi.
• Le regole leggono solo i parametri strutturati, mai la chat: un agente non può convincerle.
• Il verbale è a catena di impronte e verificabile da chiunque abbia accesso alla room.

Per segnalare un problema di sicurezza scrivi a [email protected].