Developer Hub

Documentazione API

Privion espone un'API REST completa per integrare il motore di autorizzazione nella tua infrastruttura. Tutte le risposte sono in JSON e le richieste devono essere autenticate con una API Key.

API v1.4 Stable Latenza <50ms OpenAPI 3.1

Base URL: https://api.privion.it/v1

Quick Start

Effettua la tua prima chiamata di autorizzazione in meno di 5 minuti.

Ottieni la tua API Key

Registra un account e genera la chiave API dalla dashboard. Ogni chiave è isolata per tenant.

Installa il client o usa cURL

Usa il nostro SDK Node.js/Python oppure effettua chiamate REST dirette.

Effettua la prima chiamata /evaluate

Invia il contesto e ricevi una decisione ALLOW/DENY entro 50ms.

bash — cURL

# Prima chiamata all'endpoint /evaluate
curl -X POST https://api.privion.it/v1/evaluate \
  -H "Authorization: Bearer pvn_sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userFingerprint": "usr_8f92jd...",
    "resource": "financial_records:q3",
    "action": "export",
    "context": { "trustScore": 95, "mfa_verified": true }
  }'

json — Risposta 200

{
  "allowed": true,
  "reason": "Allowed by policy: Finance Executive Access",
  "policy_id": "pol_finance_exec_v2",
  "evaluated_in_ms": 21,
  "audit_id": "aud_1f3a7b9c..."
}

Installazione Docker

Privion può essere deployato self-hosted tramite Docker Compose per ambienti on-premise o cloud privato.

yaml — docker-compose.yml

version: '3.9'
services:
  privion-api:
    image: privion/engine:latest
    ports: ["8000:8000"]
    environment:
      - MONGO_URI=mongodb://mongo:27017/privion
      - JWT_SECRET=your_secret_key
      - ENVIRONMENT=production
    depends_on: [mongo]
  mongo:
    image: mongo:7
    volumes: [mongo_data:/data/db]
volumes:
  mongo_data:

bash

docker-compose up -d
# API disponibile su http://localhost:8000

Autenticazione API

Tutte le richieste devono includere un header Authorization con una Bearer API Key.

Non esporre mai la tua API Key nel codice frontend. Usa sempre variabili di ambiente lato server.

HTTP Header

Authorization: Bearer pvn_sk_live_xxxxxxxxxxxxxxxx

POST /evaluate

Il cuore di Privion. Valuta in tempo reale se un'identità ha il permesso di compiere un'azione su una risorsa dato un contesto.

POST /v1/evaluate Valuta autorizzazione

Parametro	Tipo	Descrizione
userFingerprint req	string	Identificatore univoco utente in Privion
resource req	string	Risorsa target (es. `database_prod:records`)
action req	string	`read`, `write`, `export`, `delete`
context	object	IP, trustScore, MFA, orario, geo
tenant_id	string	Inferito dall'API Key se omesso

Gestione Policy

Le policy ABAC/RBAC definiscono chi può fare cosa in quale contesto. Gestiscile via API con versionamento completo.

GET /v1/policies Lista tutte le policy

Restituisce le policy attive del tenant con paginazione.

POST /v1/policies Crea nuova policy

Request Body

{
  "name": "Finance Executive Access",
  "effect": "Allow",
  "resource_pattern": "financial_records:*",
  "conditions": {
    "trustScore": { "gte": 80 },
    "mfa_verified": true
  }
}

GET /audit

Log immutabile di tutte le decisioni di accesso e modifiche. Ideale per compliance SOC 2 e ISO 27001.

GET /v1/audit/logs Audit log stream

Query Param	Tipo	Descrizione
from	ISO 8601	Data inizio intervallo
to	ISO 8601	Data fine intervallo
event_type	string	`EVALUATE_ACCESS`, `POLICY_UPDATE`, ecc.
limit	integer	Max risultati (default: 50, max: 500)

OpenAPI Spec

Scarica la specifica OpenAPI 3.1 completa per generare client tipizzati in qualsiasi linguaggio.

bash

curl https://api.privion.it/openapi.json -o privion-openapi.json
npx openapi-typescript privion-openapi.json -o src/types/privion.d.ts

SDK & Client

Client ufficiali con type-safety e helper pronti all'uso per Node.js e Python.

bash — Node.js

npm install @privion/sdk

javascript

import { PrivionClient } from '@privion/sdk';

const privion = new PrivionClient({ apiKey: process.env.PRIVION_API_KEY });
const result = await privion.evaluate({
  userFingerprint: 'usr_8f92j...',
  resource: 'financial_records:q3',
  action: 'export'
});
if (result.allowed) { /* procedi */ }

bash — Python

pip install privion-sdk

Codici di Errore

Privion usa codici HTTP standard. Ogni errore include un campo code leggibile.

HTTP	Codice	Descrizione
400	`INVALID_REQUEST`	Parametri mancanti o malformati
401	`UNAUTHORIZED`	API Key assente, scaduta o revocata
403	`FORBIDDEN`	Accesso negato al tenant o alla risorsa
429	`RATE_LIMITED`	Superato il limite di richieste/minuto
500	`ENGINE_ERROR`	Errore interno del Policy Engine