Riferimento API

L’API Auris è un’API REST che fornisce accesso programmatico a tutte le funzionalità IAM: autenticazione, gestione utenti, ruoli, permessi, organizzazioni, autorizzazione fine-grained e altro. Tutte le risposte API usano JSON.

URL Base

https://api.altovar.net/api

Sostituisci api.altovar.net con il dominio dove è deployato il tuo Auris. Se usi il servizio cloud Auris, il tuo dominio è quello mostrato nella Console sotto Impostazioni → Domini Personalizzati.

Autenticazione

Bearer Token

La maggior parte degli endpoint richiede un access token valido nell’header Authorization:

Authorization: Bearer <access_token>

Gli access token sono JWT a vita breve (default 15 minuti) ottenuti tramite gli endpoint di autenticazione. Sono firmati con RS256 (o HS256 a seconda della configurazione) e possono essere verificati localmente usando l’endpoint JWKS.

Livello di Accesso per Tipo di Endpoint

Header Tenant

Auris è una piattaforma multi-tenant. Le richieste agli endpoint admin devono includere l’identificatore del tenant:

x-tenant: <tenant-id>

Il tenant ID è il nome del realm configurato nel tuo deployment Auris. Per l’installazione predefinita è default. Per configurazioni tenant personalizzate, è il nome del realm mostrato nella Console sotto Impostazioni → Generale.

Se l’header viene omesso su endpoint che lo richiedono, l’API restituisce 400 Bad Request con codice MISSING_TENANT.

Formato delle Richieste

Usa Content-Type: application/json per tutte le richieste POST, PUT e PATCH con un corpo della richiesta:

Content-Type: application/json

Esempio di richiesta:

curl -X POST https://api.altovar.net/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "segreto"}'

Per il caricamento di file (importazione utenti), usa multipart/form-data.

Formato delle Risposte

Tutte le risposte API seguono un formato envelope coerente.

Risposta di Successo

{
  "ok": true,
  "data": { }
}

Il campo data contiene il risultato. La sua forma varia per endpoint ed è documentata individualmente per ogni endpoint.

Risposta di Errore

{
  "ok": false,
  "error": {
    "code": "CODICE_ERRORE",
    "message": "Descrizione leggibile di cosa è andato storto."
  }
}

Codici di Stato HTTP

Codici di Errore Comuni

Paginazione

Gli endpoint di elenco restituiscono risultati paginati usando numeri di pagina basati su cursore.

Struttura della Risposta

{
  "ok": true,
  "data": {
    "data": [],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 143,
      "totalPages": 8
    }
  }
}

Parametri di Query

Esempio:

GET /api/users?page=2&limit=50

Rate Limiting

Ogni risposta include header di rate limiting:

Quando viene superato un rate limit, l’API restituisce 429 Too Many Requests con un header Retry-After che indica quanti secondi attendere prima di riprovare.

Livelli di Rate Limiting

CORS

Il Cross-Origin Resource Sharing (CORS) è applicato su tutti gli endpoint API. Le origini consentite devono essere registrate nelle impostazioni dell’Applicazione nella Console Auris sotto Applicazioni → [App] → Origini Consentite.

Le richieste preflight OPTIONS vengono gestite automaticamente. Le credenziali (cookie) sono consentite quando l’origin della richiesta è registrata.

Per registrare un’origin:

1. Vai su Console → Applicazioni
2. Seleziona la tua applicazione
3. Aggiungi l’origin nelle Origini Consentite (es. https://app.tuodominio.com)

Discovery OIDC

Auris espone un documento di discovery OpenID Connect standard:

GET /.well-known/openid-configuration

Questo restituisce un documento JSON contenente tutti gli URL degli endpoint, i grant type supportati, gli scope, gli algoritmi di firma e altri metadati. Le librerie OIDC standard usano questo per auto-configurarsi.

Esempio di campi della risposta:

{
  "issuer": "https://api.altovar.net",
  "authorization_endpoint": "https://api.altovar.net/api/oauth/authorize",
  "token_endpoint": "https://api.altovar.net/api/auth/token",
  "userinfo_endpoint": "https://api.altovar.net/api/auth/validate",
  "jwks_uri": "https://api.altovar.net/.well-known/jwks.json",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "client_credentials", "urn:ietf:params:oauth:grant-type:device_code", "urn:ietf:params:oauth:grant-type:token-exchange"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256", "HS256"],
  "scopes_supported": ["openid", "profile", "email"]
}

JWKS

Le chiavi di firma pubbliche usate per la verifica JWT sono disponibili su:

GET /.well-known/jwks.json

Risposta:

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "key-id-1",
      "alg": "RS256",
      "n": "...",
      "e": "AQAB"
    }
  ]
}

Le chiavi vengono memorizzate nella cache dai client per un massimo di 1 ora (Cache-Control: public, max-age=3600). La rotazione delle chiavi aggiunge una nuova chiave al set; le chiavi vecchie rimangono presenti finché i token emessi non scadono.

SDK Client

Invece di chiamare direttamente l’API, considera di usare un SDK Auris che gestisce automaticamente la gestione dei token, PKCE, refresh e la gestione degli errori:

Consulta la documentazione degli SDK per le guide all’installazione e all’utilizzo.