API Organisations

L’API Organisations permet de gérer les organisations multi-tenant (B2B), leurs membres, les invitations, les connexions SSO d’entreprise et la vérification de domaines.

Tous les endpoints nécessitent le header x-tenant.

Gestion des Organisations

GET/api/organizationsRequires: manage:organizations

Liste toutes les organisations du tenant. Supporte la pagination et la recherche par nom.

Paramètres de query

Paramètre	Type	Description
`page`	integer	Numéro de page (défaut : 1)
`limit`	integer	Éléments par page (défaut : 20)
`search`	string	Recherche sur `name` et `displayName`

Réponse de succès


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "org_abc123",
        "name": "acme-corp",
        "displayName": "Acme Corporation",
        "logoUrl": "https://cdn.example.com/acme.png",
        "metadata": { "plan": "enterprise", "industry": "technology" },
        "memberCount": 45,
        "createdAt": "2024-06-01T00:00:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 3, "totalPages": 1 }
  }
}

POST/api/organizationsRequires: manage:organizations

Crée une nouvelle organisation. Le champ name est l’identifiant machine (minuscules et tirets, immuable après création). Le champ displayName est le nom affiché aux utilisateurs.

Corps de la requête


{
  "name": "acme-corp",
  "displayName": "Acme Corporation",
  "logoUrl": "https://cdn.example.com/acme.png",
  "metadata": {
    "plan": "enterprise",
    "industry": "technology"
  }
}

Codes d’erreur

Code	HTTP	Description
`NAME_TAKEN`	409	Une organisation avec ce `name` existe déjà
`VALIDATION_ERROR`	400	Format du `name` invalide (doit être en minuscules avec tirets)

Le champ name est immuable après la création. Choisis-le soigneusement car il est utilisé dans les URLs et les références SSO.

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

Obtient une organisation par son ID.

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

Met à jour displayName, logoUrl ou metadata. Le champ name ne peut pas être modifié.

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

Supprime une organisation. Cette action supprime également tous les membres, invitations et connexions SSO associés à cette organisation. Action irréversible.

La suppression d’une organisation est irréversible. Tous les membres, invitations, connexions SSO et associations de domaines seront supprimés définitivement.

Gestion des Membres

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

Liste les membres de l’organisation avec leur rôle.

Réponse de succès


{
  "ok": true,
  "data": {
    "data": [
      {
        "userId": "usr_abc123",
        "email": "[email protected]",
        "name": "Alice Martin",
        "role": "OWNER",
        "joinedAt": "2024-06-01T00:00:00Z"
      }
    ]
  }
}

Rôles organisationnels

Rôle	Description
`OWNER`	Accès complet, peut supprimer l’organisation. Doit toujours rester au moins un owner.
`ADMIN`	Peut gérer les membres, les connexions SSO et les paramètres de l’organisation.
`MEMBER`	Membre standard avec accès aux ressources partagées.
`VIEWER`	Accès en lecture seule aux ressources de l’organisation.

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

Ajoute un utilisateur existant à l’organisation.

Corps de la requête


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

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

Met à jour le rôle d’un membre dans l’organisation.

Corps de la requête


{
  "role": "ADMIN"
}

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

Retire un membre de l’organisation.

Codes d’erreur

Code	HTTP	Description
`LAST_OWNER`	400	Impossible de retirer le dernier owner de l’organisation

Invitations

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

Liste les invitations actives et expirées pour l’organisation.

Réponse de succès


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "inv_abc123",
        "email": "[email protected]",
        "role": "MEMBER",
        "status": "pending",
        "invitedBy": "usr_owner123",
        "expiresAt": "2025-03-10T00:00:00Z",
        "createdAt": "2025-03-03T00:00:00Z"
      }
    ]
  }
}

Statuts des invitations

Statut	Description
`pending`	Invitation envoyée, en attente de réponse
`accepted`	L’utilisateur a accepté l’invitation
`expired`	L’invitation a expiré après 7 jours sans réponse
`cancelled`	L’invitation a été annulée manuellement

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

Envoie une invitation par email. Si l’email correspond à un utilisateur existant du tenant, le flux d’acceptation est simplifié. Les invitations expirent après 7 jours.

Corps de la requête


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

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

Annule une invitation en attente. Les invitations déjà acceptées ne peuvent pas être annulées (retire plutôt le membre).

Connexions SSO

Les connexions SSO d’entreprise permettent aux membres d’une organisation de s’authentifier via leur propre fournisseur d’identité (IdP).

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

Liste toutes les connexions SSO pour l’organisation.

Réponse de succès


{
  "ok": true,
  "data": [
    {
      "id": "sso_abc123",
      "type": "saml",
      "status": "ACTIVE",
      "name": "Connexion SAML Acme",
      "domain": "acme.com",
      "acsUrl": "https://auth.yourdomain.com/sso/saml/callback",
      "entityId": "https://auth.yourdomain.com",
      "createdAt": "2025-01-15T00:00:00Z"
    }
  ]
}

Statuts SSO

Statut	Description
`PENDING`	Connexion créée mais non encore activée
`ACTIVE`	La connexion est active et accepte les authentifications
`DISABLED`	La connexion a été désactivée manuellement
`ERROR`	La connexion a rencontré une erreur (ex. métadonnées invalides)

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

Crée une nouvelle connexion SSO. Supporte les protocoles SAML 2.0 et OIDC.

Corps de la requête — SAML


{
  "type": "saml",
  "name": "Connexion SAML Acme",
  "metadataUrl": "https://idp.acme.com/metadata"
}

Ou avec métadonnées XML directes :


{
  "type": "saml",
  "name": "Connexion SAML Acme",
  "metadataXml": "<EntityDescriptor ...>...</EntityDescriptor>"
}

Corps de la requête — OIDC


{
  "type": "oidc",
  "name": "Connexion OIDC Acme",
  "discoveryUrl": "https://idp.acme.com/.well-known/openid-configuration",
  "clientId": "auris-sp-client",
  "clientSecret": "secret_value"
}

Réponse de succès

La réponse inclut acsUrl (Assertion Consumer Service URL) et entityId pour la configuration côté IdP :


{
  "ok": true,
  "data": {
    "id": "sso_def456",
    "type": "saml",
    "status": "PENDING",
    "name": "Connexion SAML Acme",
    "acsUrl": "https://auth.yourdomain.com/sso/saml/callback",
    "entityId": "https://auth.yourdomain.com",
    "createdAt": "2025-03-01T00:00:00Z"
  }
}

Après la création, configure ton IdP avec les valeurs acsUrl et entityId retournées, puis active la connexion avec l’endpoint d’activation.

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

Active la connexion SSO. Valide les métadonnées avant l’activation. En cas d’erreur de validation, retourne les détails de l’erreur.

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

Désactive la connexion SSO. Les authentifications via cette connexion seront rejetées.

Vérification de Domaines

La vérification de domaines permet de prouver la propriété d’un domaine pour activer des fonctionnalités comme la détection automatique du SSO.

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

Liste les domaines vérifiés et en attente de vérification pour l’organisation.

Réponse de succès


{
  "ok": true,
  "data": [
    {
      "id": "dom_abc123",
      "domain": "acme.com",
      "status": "ACTIVE",
      "txtRecord": "_auris-verify.acme.com",
      "txtValue": "auris-verify=abc123def456",
      "verifiedAt": "2025-02-01T00:00:00Z"
    }
  ]
}

Statuts des domaines

Statut	Description
`PENDING`	Domaine ajouté, enregistrement TXT non encore créé
`VERIFYING`	Vérification en cours
`ACTIVE`	Domaine vérifié avec succès
`FAILED`	Vérification échouée (enregistrement TXT introuvable ou invalide)

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

Initie la vérification d’un domaine. Retourne l’enregistrement TXT DNS à créer pour prouver la propriété.

Corps de la requête


{
  "domain": "acme.com"
}

Réponse de succès


{
  "ok": true,
  "data": {
    "id": "dom_def456",
    "domain": "acme.com",
    "status": "PENDING",
    "txtRecord": "_auris-verify.acme.com",
    "txtValue": "auris-verify=abc123def456",
    "instructions": "Crée un enregistrement TXT DNS pour '_auris-verify.acme.com' avec la valeur 'auris-verify=abc123def456', puis appelle l'endpoint de vérification."
  }
}

Format de l’enregistrement TXT : Crée un enregistrement DNS de type TXT pour _auris-verify.{ton-domaine} avec la valeur retournée par l’API. La propagation DNS peut prendre jusqu’à 48 heures.

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

Déclenche une vérification de l’enregistrement TXT DNS pour confirmer la propriété du domaine. Si l’enregistrement est trouvé et valide, le statut passe à ACTIVE.

Pages Associées

Multi-Tenant (Concept) — Architecture multi-tenant dans Auris
Guide B2B Multi-Tenant — Implémenter les organisations B2B
SSO d’Entreprise — Configurer le SSO SAML/OIDC
Organisations (Console) — Gérer les organisations depuis la Console
API SSO — Configuration globale du SSO