API Organizzazioni

Le organizzazioni sono il livello di multi-tenancy B2B in Auris. Un’organizzazione rappresenta un’azienda cliente all’interno del tenant — con i propri membri, ruoli, configurazione SSO e verifica del dominio. Gli utenti possono appartenere a più organizzazioni con ruoli diversi in ciascuna.

Ruoli dei membri dell’organizzazione: OWNER (controllo completo), ADMIN (gestisce membri e impostazioni), MEMBER (accesso standard), VIEWER (sola lettura).

Tutti gli endpoint richiedono l’header x-tenant e il permesso manage:organizations salvo diversa indicazione.

CRUD Organizzazioni

GET/api/organizationsRequires: manage:organizations

Elenca tutte le organizzazioni nel tenant. Restituisce informazioni di riepilogo incluso il numero di membri e se è configurata una connessione SSO.

Parametri di query

Parametro	Tipo	Descrizione
`page`	integer	Numero di pagina (default: 1)
`limit`	integer	Elementi per pagina (default: 20)
`search`	string	Cerca per nome organizzazione o nome visualizzato

Risposta di successo


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "org_abc123",
        "name": "acme-corp",
        "displayName": "Acme Corporation",
        "memberCount": 45,
        "hasSso": true,
        "createdAt": "2025-01-01T00:00:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 12, "totalPages": 1 }
  }
}

POST/api/organizationsRequires: manage:organizations

Crea una nuova organizzazione. Il name è un identificatore leggibile dalla macchina (minuscolo, trattini consentiti) che deve essere unico nel tenant. Il displayName è il nome leggibile dall’utente mostrato nell’interfaccia.

Corpo della richiesta


{
  "name": "acme-corp",
  "displayName": "Acme Corporation",
  "metadata": {
    "industry": "Manifatturiero",
    "country": "IT"
  }
}

displayName e metadata sono opzionali.

Risposta di successo


{
  "ok": true,
  "data": {
    "id": "org_def456",
    "name": "acme-corp",
    "displayName": "Acme Corporation",
    "metadata": { "industry": "Manifatturiero", "country": "IT" },
    "memberCount": 0,
    "createdAt": "2025-02-18T10:00:00Z"
  }
}

Codici di errore

Codice	HTTP	Descrizione
`NAME_TAKEN`	409	Esiste già un’organizzazione con questo nome
`VALIDATION_ERROR`	400	Nome organizzazione non valido (deve essere alfanumerico minuscolo con trattini)

GET/api/organizations/[id]Requires: manage:organizations

Ottieni i dettagli completi di un’organizzazione, inclusi i metadati e lo stato SSO.

Risposta di successo


{
  "ok": true,
  "data": {
    "id": "org_abc123",
    "name": "acme-corp",
    "displayName": "Acme Corporation",
    "metadata": { "industry": "Manifatturiero" },
    "memberCount": 45,
    "hasSso": true,
    "ssoProvider": "saml",
    "verifiedDomains": ["acme-corp.it"],
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-02-01T12:00:00Z"
  }
}

PUT/api/organizations/[id]Requires: manage:organizations

Aggiorna il nome visualizzato o i metadati di un’organizzazione. Il name (identificatore macchina) non può essere modificato dopo la creazione.

Corpo della richiesta


{
  "displayName": "Acme Corp International",
  "metadata": {
    "industry": "Manifatturiero",
    "country": "IT",
    "tier": "enterprise"
  }
}

Risposta di successo


{
  "ok": true,
  "data": {
    "id": "org_abc123",
    "displayName": "Acme Corp International",
    "metadata": { "industry": "Manifatturiero", "country": "IT", "tier": "enterprise" }
  }
}

DELETE/api/organizations/[id]Requires: manage:organizations

Elimina un’organizzazione. Tutti i membri vengono rimossi dall’organizzazione. Le connessioni SSO e le verifiche del dominio vengono eliminate. Gli account utente stessi non vengono eliminati.

Risposta di successo


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

Gestione Membri

GET/api/organizations/[id]/membersRequires: manage:organizations

Elenca tutti i membri di un’organizzazione con i loro ruoli e le date di iscrizione.

Parametri di query

Parametro	Tipo	Descrizione
`page`	integer	Numero di pagina (default: 1)
`limit`	integer	Elementi per pagina (default: 20)
`role`	`OWNER` \| `ADMIN` \| `MEMBER` \| `VIEWER`	Filtra per ruolo

Risposta di successo


{
  "ok": true,
  "data": {
    "data": [
      {
        "userId": "usr_abc123",
        "email": "[email protected]",
        "firstName": "Alice",
        "lastName": "Rossi",
        "role": "ADMIN",
        "joinedAt": "2025-01-15T10:00:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 45, "totalPages": 3 }
  }
}

POST/api/organizations/[id]/membersRequires: manage:organizations

Aggiungi un utente esistente (tramite ID utente) all’organizzazione con un ruolo specificato. Per aggiungere utenti che non hanno ancora un account, usa gli endpoint di invito.

Corpo della richiesta


{
  "userId": "usr_abc123",
  "role": "MEMBER"
}

Risposta di successo


{
  "ok": true,
  "data": {
    "userId": "usr_abc123",
    "role": "MEMBER",
    "joinedAt": "2025-02-18T11:00:00Z"
  }
}

Codici di errore

Codice	HTTP	Descrizione
`USER_NOT_FOUND`	404	L’utente non esiste in questo tenant
`ALREADY_MEMBER`	409	L’utente è già un membro di questa organizzazione

PATCH/api/organizations/[id]/members/[userId]Requires: manage:organizations

Aggiorna il ruolo di un membro nell’organizzazione. Solo i membri OWNER e ADMIN possono essere modificati. Un’organizzazione deve sempre avere almeno un OWNER.

Corpo della richiesta


{
  "role": "ADMIN"
}

Risposta di successo


{
  "ok": true,
  "data": {
    "userId": "usr_abc123",
    "role": "ADMIN",
    "updatedAt": "2025-02-18T12:00:00Z"
  }
}

Codici di errore

Codice	HTTP	Descrizione
`LAST_OWNER`	400	Non è possibile rimuovere l’ultimo OWNER da un’organizzazione

DELETE/api/organizations/[id]/members/[userId]Requires: manage:organizations

Rimuovi un membro dall’organizzazione. L’account utente non viene eliminato.

Risposta di successo


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

Inviti

GET/api/organizations/[id]/invitationsRequires: manage:organizations

Elenca tutti gli inviti in sospeso per un’organizzazione.

Risposta di successo


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "inv_abc123",
        "email": "[email protected]",
        "role": "MEMBER",
        "status": "pending",
        "expiresAt": "2025-02-25T10:00:00Z",
        "createdAt": "2025-02-18T10:00:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 2, "totalPages": 1 }
  }
}

Stati dell’invito: pending, accepted, expired, cancelled.

POST/api/organizations/[id]/invitationsRequires: manage:organizations

Invita un utente nell’organizzazione tramite email. Viene inviata un’email di invito con un link di accettazione basato su token. Gli inviti scadono dopo 7 giorni. Se l’email è già associata a un utente del tenant, viene notificato direttamente. In caso contrario, viene invitato a creare prima un account.

Corpo della richiesta


{
  "email": "[email protected]",
  "role": "MEMBER"
}

Risposta di successo


{
  "ok": true,
  "data": {
    "id": "inv_def456",
    "email": "[email protected]",
    "role": "MEMBER",
    "expiresAt": "2025-02-25T10:00:00Z"
  }
}

Codici di errore

Codice	HTTP	Descrizione
`ALREADY_MEMBER`	409	L’email è già un membro attivo di questa organizzazione
`INVITATION_PENDING`	409	Esiste già un invito in sospeso per questa email

DELETE/api/organizations/[id]/invitations/[invId]Requires: manage:organizations

Annulla un invito in sospeso. Il link di invito nell’email diventa immediatamente non valido.

Risposta di successo


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

Enterprise SSO

L’Enterprise SSO (Single Sign-On) consente ai membri dell’organizzazione di autenticarsi usando il proprio provider di identità (IdP) esistente — SAML 2.0 o basato su OIDC. Le connessioni SSO sono con scope sull’organizzazione e si attivano automaticamente quando gli utenti accedono con un’email di dominio verificato.

Tutti gli endpoint SSO richiedono manage:sso_connections.

GET/api/organizations/[orgId]/sso/connectionsRequires: manage:sso_connections

Elenca tutte le connessioni SSO configurate per un’organizzazione.

Risposta di successo


{
  "ok": true,
  "data": [
    {
      "id": "sso_abc123",
      "type": "saml",
      "status": "ACTIVE",
      "keycloakIdpAlias": "acme-saml",
      "domains": ["acme-corp.it"],
      "createdAt": "2025-01-20T09:00:00Z"
    }
  ]
}

Stati della connessione SSO: PENDING (configurata ma non attivata), ACTIVE, DISABLED, ERROR.

POST/api/organizations/[orgId]/sso/connectionsRequires: manage:sso_connections

Crea una nuova connessione SSO. Per SAML, fornisci l’URL dei metadati IdP o XML grezzo. Per OIDC, fornisci l’URL di discovery e le credenziali client.

Corpo della richiesta — SAML


{
  "type": "saml",
  "name": "IdP Aziendale Acme",
  "config": {
    "metadataUrl": "https://idp.acme-corp.it/metadata",
    "entityId": "https://idp.acme-corp.it",
    "ssoUrl": "https://idp.acme-corp.it/sso",
    "certificate": "-----BEGIN CERTIFICATE-----\n..."
  }
}

Corpo della richiesta — OIDC


{
  "type": "oidc",
  "name": "Acme OIDC",
  "config": {
    "discoveryUrl": "https://login.acme-corp.it/.well-known/openid-configuration",
    "clientId": "auris-sp-client",
    "clientSecret": "sp-client-secret"
  }
}

Risposta di successo


{
  "ok": true,
  "data": {
    "id": "sso_def456",
    "type": "saml",
    "status": "PENDING",
    "keycloakIdpAlias": "acme-saml-def456",
    "acsUrl": "https://api.altovar.net/api/auth/sso/callback",
    "entityId": "https://api.altovar.net"
  }
}

L’acsUrl (Assertion Consumer Service URL) e l’entityId sono valori da fornire all’IdP durante la configurazione SP.

POST/api/organizations/[orgId]/sso/connections/[id]/activateRequires: manage:sso_connections

Attiva una connessione SSO. Dopo l’attivazione, gli utenti con un’email di dominio verificato vengono automaticamente reindirizzati al provider SSO al login.

Richiesta: Nessun corpo richiesto.

Risposta di successo


{
  "ok": true,
  "data": { "activated": true, "status": "ACTIVE" }
}

POST/api/organizations/[orgId]/sso/connections/[id]/deactivateRequires: manage:sso_connections

Disattiva una connessione SSO. Gli utenti con email di dominio torneranno all’autenticazione standard con password finché l’SSO non viene riattivato.

Richiesta: Nessun corpo richiesto.

Risposta di successo


{
  "ok": true,
  "data": { "deactivated": true, "status": "DISABLED" }
}

Verifica Dominio

La verifica del dominio prova che controlli un dominio prima di abilitare il reindirizzamento automatico SSO per gli indirizzi email su quel dominio. La verifica avviene tramite un record DNS TXT.

GET/api/organizations/[orgId]/sso/domainsRequires: manage:sso_connections

Elenca tutti i domini associati alla configurazione SSO di un’organizzazione, incluso lo stato di verifica.

Risposta di successo


{
  "ok": true,
  "data": [
    {
      "id": "dom_abc123",
      "domain": "acme-corp.it",
      "status": "ACTIVE",
      "verificationMethod": "TXT",
      "verificationToken": "auris-verify-abc123def456",
      "verifiedAt": "2025-01-22T14:00:00Z"
    }
  ]
}

Stati di verifica dominio: PENDING, VERIFYING, ACTIVE, FAILED.

POST/api/organizations/[orgId]/sso/domainsRequires: manage:sso_connections

Aggiungi un dominio e avvia la verifica. Viene restituito un verificationToken che deve essere aggiunto come record DNS TXT sul dominio. Poi chiama l’endpoint di check per confermare.

Corpo della richiesta


{
  "domain": "acme-corp.it"
}

Risposta di successo


{
  "ok": true,
  "data": {
    "id": "dom_def456",
    "domain": "acme-corp.it",
    "status": "PENDING",
    "verificationMethod": "TXT",
    "verificationToken": "auris-verify-ghi789jkl012",
    "dnsRecord": {
      "type": "TXT",
      "host": "_auris-verify.acme-corp.it",
      "value": "auris-verify-ghi789jkl012"
    }
  }
}

Aggiungi il record DNS TXT mostrato in dnsRecord presso il tuo registrar di dominio, poi chiama l’endpoint di check.

POST/api/organizations/[orgId]/sso/domains/[id]/checkRequires: manage:sso_connections

Avvia la verifica DNS per un dominio. Auris esegue una ricerca DNS TXT live per verificare il token di verifica. Restituisce il nuovo stato immediatamente.

Richiesta: Nessun corpo richiesto.

Risposta di successo — verificato


{
  "ok": true,
  "data": {
    "domain": "acme-corp.it",
    "status": "ACTIVE",
    "verifiedAt": "2025-02-18T15:00:00Z"
  }
}

Risposta di successo — non ancora propagato


{
  "ok": true,
  "data": {
    "domain": "acme-corp.it",
    "status": "PENDING",
    "message": "Record TXT non ancora trovato. La propagazione DNS può richiedere fino a 48 ore."
  }
}

La propagazione DNS richiede tipicamente pochi minuti ma in casi rari può richiedere fino a 48 ore. Chiama periodicamente l’endpoint di check finché lo stato non diventa ACTIVE.

Pagine Correlate

Multi-Tenancy — Come le organizzazioni si mappano ai tenant Auris
Guida Multi-Tenant B2B — Configura l’architettura multi-organizzazione
Enterprise SSO — Configura SSO per i membri dell’organizzazione
Organizzazioni — Gestisci le organizzazioni dalla Console
API SSO — Endpoint per le connessioni Enterprise SSO