Documentation

Premiers pas

Authagonal fournit a chaque tenant un serveur OIDC entierement conforme aux standards. Chaque tenant obtient sa propre URL d'emetteur, son document de decouverte et ses points de terminaison de jetons -- aucune infrastructure partagee entre les tenants. Vous pouvez passer de zero a un flux de connexion fonctionnel en moins de 5 minutes.

Creer un tenant

Inscrivez-vous sur authagonal.io et choisissez un slug pour votre tenant. Le slug devient votre domaine d'emetteur : {slug}.authagonal.io. Apres avoir cree votre compte, verifiez votre adresse e-mail pour activer le tenant.

Choisissez un slug unique pour votre tenant lors de l'inscription

Enregistrer un client

Naviguez vers Clients dans la barre laterale du portail et cliquez sur Creer. Entrez un clientId et un clientName pour votre application. Ensuite, configurez au moins une URI de redirection -- c'est la ou les utilisateurs sont envoyes apres l'authentification. Par exemple : https://app.example.com/callback.

Enregistrer un nouveau client OAuth dans le portail

Votre premiere connexion

Le moyen le plus rapide de s'integrer est avec oidc-client-ts, une bibliotheque client OIDC legere pour les applications JavaScript et TypeScript.

import { UserManager } from 'oidc-client-ts';

const mgr = new UserManager({
  authority: 'https://acme.authagonal.io',
  client_id: 'my-app',
  redirect_uri: 'https://app.example.com/callback',
  response_type: 'code',
  scope: 'openid profile email',
});

// Redirect to login
mgr.signinRedirect();

// On callback page
const user = await mgr.signinRedirectCallback();
console.log(user.profile); // { sub, email, name, ... }

Si vous preferez une approche minimale sans bibliotheque, vous pouvez utiliser le flux standard OAuth 2.0 authorization code avec un simple fetch :

// 1. Redirect the user to the authorization endpoint
const authorizeUrl = new URL('https://acme.authagonal.io/connect/authorize');
authorizeUrl.searchParams.set('client_id', 'my-app');
authorizeUrl.searchParams.set('redirect_uri', 'https://app.example.com/callback');
authorizeUrl.searchParams.set('response_type', 'code');
authorizeUrl.searchParams.set('scope', 'openid profile email');
authorizeUrl.searchParams.set('code_challenge', codeChallenge);
authorizeUrl.searchParams.set('code_challenge_method', 'S256');
window.location.href = authorizeUrl.toString();

// 2. On the callback page, exchange the code for tokens
const res = await fetch('https://acme.authagonal.io/connect/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: new URLSearchParams(window.location.search).get('code')!,
    redirect_uri: 'https://app.example.com/callback',
    client_id: 'my-app',
    code_verifier: codeVerifier,
  }),
});

const tokens = await res.json();
// tokens.id_token, tokens.access_token, tokens.refresh_token

La page de connexion par defaut de votre tenant

Tableau de bord

Le tableau de bord du portail vous donne un apercu en temps reel de votre tenant. Il met en evidence les metriques les plus importantes -- croissance des utilisateurs, activite d'authentification et navigation rapide vers chaque fonctionnalite du portail.

Vue d'ensemble

En haut du tableau de bord, vous verrez un message de bienvenue ainsi que votre nombre total d'utilisateurs actuel. En dessous, un graphique Utilisateurs actifs quotidiens affiche un historique sur 7 jours des utilisateurs uniques qui se sont authentifies chaque jour, vous donnant un apercu rapide des tendances d'engagement.

L'ecran d'accueil du tableau de bord avec le graphique DAU et l'apercu de l'activite

Metriques d'activite

Le panneau de metriques d'activite affiche quatre cartes de statistiques resumant les principaux evenements d'authentification :

• Connexions reussies -- flux d'authentification completes
• Connexions echouees -- identifiants incorrects, comptes verrouilles ou rejets de politique
• Utilisateurs actifs -- utilisateurs uniques qui se sont authentifies pendant la periode selectionnee
• Operations SCIM -- evenements de provisionnement d'utilisateurs et de groupes depuis les IdP connectes

Utilisez les filtres de plage temporelle pour basculer entre 24 heures, 3 jours, 7 jours et 30 jours. Toutes les cartes de statistiques et les graphiques se mettent a jour pour refleter la fenetre selectionnee.

Metriques d'activite avec plage temporelle configurable

Navigation rapide

Sous le panneau de metriques, des cartes de navigation renvoient directement vers chaque fonctionnalite majeure : Clients, Utilisateurs, Groupes, Roles, SSO, SCIM, Personnalisation et Parametres. Chaque carte affiche une breve description pour que les nouveaux membres de l'equipe puissent s'orienter rapidement.

Clients

Les clients OAuth representent les applications qui authentifient les utilisateurs via votre tenant. Chaque client a sa propre configuration pour les URI de redirection, les scopes, les types de grants, les durees de vie des jetons et la politique MFA.

Liste des clients

La page Clients affiche un tableau de tous les clients enregistres. Chaque ligne montre le clientId, le nom d'affichage, les types de grants autorises sous forme de badges colores, et si PKCE est active. Cliquez sur n'importe quelle ligne pour ouvrir l'editeur de configuration complet.

Liste des clients avec badges de types de grants et indicateurs PKCE

Creer un client

Cliquez sur Creer un client pour enregistrer une nouvelle application. Vous devez fournir deux champs :

• clientId -- un identifiant unique pour le client (par ex. my-spa)
• clientName -- un nom d'affichage lisible

Enregistrer un nouveau client OAuth

Supprimer un client

Pour supprimer un client, ouvrez la configuration du client et cliquez sur le bouton Supprimer le client en bas de la page. Une confirmation vous sera demandee avant que le client ne soit definitivement supprime. Toutes les sessions actives et les jetons du client supprime sont immediatement invalides.

Reference de configuration du client

Chaque client dispose d'un ensemble complet d'options de configuration organisees en plusieurs sections.

Parametres generaux

URIs

Les champs URI utilisent une saisie par tags -- tapez une valeur et appuyez sur Entree ou virgule pour l'ajouter. Cliquez sur le X d'un tag pour le supprimer.

Champs de saisie par tags pour la configuration des URIs

Scopes et types de grants

Durees de vie des jetons

Configurer les durees de vie des jetons par client

URI de déconnexion

Les clients peuvent enregistrer des URI de déconnexion back-channel et front-channel. Les deux sont optionnelles — configurez celle qui correspond à la façon dont votre application efface sa session.

Politique MFA

Chaque client peut remplacer la politique MFA du tenant par un parametre par client. Le menu deroulant de politique MFA propose trois options :

Remplacement de politique MFA par client

SSO Entreprise

Le SSO entreprise permet a vos clients d'utiliser leur propre fournisseur d'identite. Authagonal prend en charge la federation SAML 2.0 et OIDC avec routage par domaine, de sorte que les utilisateurs sont automatiquement diriges vers le bon IdP en fonction de leur adresse e-mail.

Routage SSO par domaine

Connexions SAML 2.0

Pour creer une connexion SAML, naviguez vers la page SSO et selectionnez l'onglet SAML. Fournissez les informations suivantes :

Lorsque vous enregistrez la connexion, Authagonal recupere le document de metadonnees et importe le certificat de signature de l'IdP, l'URL du point de terminaison SSO et le format d'identifiant de nom. Les metadonnees sont periodiquement rafraichies pour prendre en compte les rotations de certificats.

Creer une connexion SSO SAML 2.0

Connexions OIDC

Pour creer une connexion de federation OIDC, selectionnez l'onglet OIDC et fournissez :

Creer une connexion de federation OIDC

Routage par domaine

Le routage par domaine redirige automatiquement les utilisateurs vers le bon fournisseur d'identite en fonction de leur domaine d'e-mail. Lorsqu'un utilisateur entre son e-mail sur la page de connexion, Authagonal verifie si la partie domaine (par ex. acme.com) correspond a une connexion SSO configuree. Si c'est le cas, l'utilisateur est redirige de maniere transparente vers l'IdP de son organisation.

Le routage par domaine associe les domaines d'e-mail aux fournisseurs d'identite

Provisionnement JIT

Par defaut, lorsqu'un utilisateur se connecte via SSO pour la premiere fois et n'existe pas encore dans votre tenant, Authagonal cree automatiquement son compte (provisionnement Just-In-Time). Cela peut etre desactive par connexion en cochant Desactiver le provisionnement JIT lors de la creation ou de la modification de la connexion.

Lorsque le provisionnement JIT est desactive, seuls les utilisateurs qui ont ete pre-provisionnes -- via SCIM, la page Utilisateurs du portail ou l'API -- peuvent se connecter via cette connexion. Les utilisateurs inconnus recoivent une erreur access_denied et sont invites a contacter leur administrateur.

Utilisateurs

La page Utilisateurs vous permet de gerer tous les utilisateurs finaux de votre tenant. Vous pouvez rechercher des utilisateurs, voir leurs details, creer de nouveaux comptes et voir comment chaque utilisateur a ete provisionne.

Recherche et pagination

La barre de recherche prend en charge le filtrage par adresse e-mail ou identifiant utilisateur. La recherche est debounced a 300 ms pour que les resultats se mettent a jour au fur et a mesure de la saisie sans surcharger l'API. Les resultats sont pagines a 50 utilisateurs par page -- utilisez les controles de navigation en bas du tableau pour naviguer entre les pages.

Tableau des utilisateurs

Le tableau des utilisateurs affiche les colonnes suivantes pour chaque utilisateur :

La liste des utilisateurs avec barre de recherche et pagination

Creer des utilisateurs

Cliquez sur Creer un utilisateur pour ajouter un nouvel utilisateur local. Le formulaire requiert :

Creer un nouvel utilisateur local

Détail de l'utilisateur

Cliquez sur n'importe quelle ligne de la liste des utilisateurs pour ouvrir sa page de détail. De là, vous pouvez modifier les données du profil, gérer les rôles, réinitialiser la MFA, consulter les attributs personnalisés et supprimer l'utilisateur.

Profil

Modifiez l'e-mail, le prénom/nom, le téléphone, l'entreprise, l'ID externe et l'indicateur actif de l'utilisateur. Les changements d'e-mail doivent rester uniques dans le tenant ; l'API renvoie email_in_use s'il est déjà pris.

Rôles

Attribuez et retirez les rôles définis sur la page Rôles. L'appartenance aux rôles est incluse dans les jetons ID et d'accès lorsque le client a includeRolesInTokens activé.

Authentification multifacteur

Consultez chaque identifiant MFA enregistré pour l'utilisateur — application d'authentification (TOTP), WebAuthn/passkeys et codes de récupération — chacun avec ses horodatages d'enregistrement et de dernière utilisation. Supprimez des identifiants individuels ou réinitialisez toute la MFA. Réinitialiser force l'utilisateur à s'inscrire à nouveau à sa prochaine connexion.

Attributs personnalisés

Données clé/valeur arbitraires attachées à l'utilisateur. Les clés doivent être uniques. Les attributs sont exposés via l'API de profil utilisateur et SCIM, et peuvent être mappés sur des claims du jeton d'accès en configurant les userClaims d'un scope personnalisé.

Supprimer l'utilisateur

Supprime définitivement l'utilisateur et toutes ses identifiants MFA. Saisissez l'e-mail de l'utilisateur pour confirmer — aucune annulation possible.

Groupes

Les groupes vous permettent d'organiser les utilisateurs et d'inclure l'appartenance aux groupes dans les jetons. Les groupes peuvent etre crees manuellement dans le portail ou provisionnes automatiquement via SCIM depuis un fournisseur d'identite externe.

Liste des groupes

La page Groupes affiche tous les groupes de votre tenant avec les informations suivantes :

Liste des groupes avec indicateurs de source

Creer un groupe

Cliquez sur Creer un groupe et entrez un displayName pour le groupe. Les noms de groupes doivent etre descriptifs et uniques au sein de votre tenant (par ex. "Engineering", "Billing Admins", "Beta Testers").

Detail du groupe et membres

Cliquez sur n'importe quel groupe pour ouvrir la vue de detail. Ici, vous pouvez voir tous les membres actuels et gerer l'appartenance :

• Ajouter des membres -- Entrez un identifiant utilisateur pour ajouter un utilisateur au groupe.
• Supprimer des membres -- Cliquez sur le bouton de suppression a cote d'un membre pour le retirer individuellement.

Gerer l'appartenance au groupe dans la vue de detail

Groupes dans les jetons

Lorsque includeGroupsInTokens est active sur un client, le jeton ID inclut un claim groups contenant les appartenances aux groupes de l'utilisateur. Chaque entree inclut l'id et le name du groupe :

{
  "sub": "user-123",
  "email": "jane@acme.com",
  "groups": [
    { "id": "grp-001", "name": "Engineering" },
    { "id": "grp-002", "name": "Beta Testers" }
  ]
}

Roles

Les roles prennent en charge le controle d'acces base sur les roles (RBAC) dans votre application. Definissez les roles dans Authagonal, assignez-les aux utilisateurs et utilisez le claim roles dans les jetons pour appliquer l'autorisation dans la logique de votre application.

Gestion des roles

La page Roles affiche un tableau de tous les roles definis avec edition en ligne. Chaque role possede :

Creer un role

Cliquez sur Creer un role et fournissez un nom et une description. Les noms de roles doivent etre concis et suivre une convention de nommage coherente dans votre application (par ex. minuscules avec tirets : billing-admin).

Edition en ligne

Les roles supportent l'edition en ligne directement dans le tableau. Cliquez sur l'icone de crayon sur n'importe quel role pour entrer en mode edition -- les champs de nom et de description deviennent modifiables. Modifiez les valeurs, puis cliquez sur l'icone de coche pour enregistrer. Les modifications prennent effet immediatement.

Supprimer un role

Cliquez sur l'icone de suppression sur n'importe quel role pour le retirer. Une confirmation vous sera demandee avant que le role ne soit definitivement supprime. La suppression d'un role n'invalide pas retroactivement les jetons existants -- le role sera absent des nouveaux jetons emis apres la suppression.

Edition en ligne des roles dans le tableau des roles

Roles dans les jetons

Les roles assignes a un utilisateur sont inclus en tant que claim roles dans le jeton ID. Votre application peut lire ce claim pour prendre des decisions d'autorisation :

{
  "sub": "user-123",
  "email": "jane@acme.com",
  "roles": ["admin", "billing-admin"]
}

Provisionnement SCIM

SCIM 2.0 (System for Cross-domain Identity Management) permet le provisionnement automatique des utilisateurs et des groupes depuis les fournisseurs d'identite d'entreprise comme Okta, Azure AD, OneLogin et JumpCloud. Une fois configure, les comptes utilisateurs et les appartenances aux groupes sont automatiquement synchronises depuis l'IdP en amont vers votre tenant Authagonal.

Synchronisation du cycle de vie des utilisateurs SCIM avec provisionnement en aval

Etapes de configuration

Suivez ces etapes pour activer le provisionnement SCIM pour un client :

1. Selectionnez l'application cliente -- Choisissez le client OAuth auquel le provisionnement SCIM sera associe.
2. Generez un jeton SCIM -- Fournissez une description et une periode d'expiration en jours, puis generez le jeton.
3. Copiez le jeton immediatement -- La valeur brute du jeton n'est affichee qu'une seule fois. Copiez-la avant de fermer la boite de dialogue.
4. Configurez votre IdP -- Dans les parametres SCIM de votre fournisseur d'identite, entrez l'URL de base et le jeton bearer.
5. Testez la synchronisation des utilisateurs -- Declenchez une synchronisation de test depuis votre IdP et verifiez que les utilisateurs apparaissent dans le portail Authagonal.

URL de base SCIM

Configurez votre fournisseur d'identite avec l'URL de base suivante :

https://{slug}.authagonal.io/scim/v2

Remplacez {slug} par le slug de votre tenant.

Page de configuration SCIM avec generation de jetons

Gestion des jetons

Les jetons SCIM authentifient les requetes de provisionnement depuis votre IdP. Vous pouvez gerer plusieurs jetons par client :

Pour revoquer un jeton, cliquez sur le bouton Revoquer a cote de celui-ci. Les jetons revoques restent visibles dans la liste a des fins d'audit mais cessent immediatement d'accepter les requetes.

Gestion des jetons avec indicateurs de jetons actifs et revoques

Test de connectivite

Verifiez que votre integration SCIM fonctionne en interrogeant le point de terminaison ServiceProviderConfig :

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://acme.authagonal.io/scim/v2/ServiceProviderConfig

Une reponse reussie renvoie un document JSON decrivant les fonctionnalites SCIM prises en charge, y compris les operations en masse, le filtrage et la capacite de changement de mot de passe.

Scopes OAuth

Les scopes permettent aux clients de demander des portions spécifiques des données ou autorisations d'un utilisateur. Authagonal prend en charge les scopes OIDC standards et les scopes personnalisés que vous définissez pour vos API.

Scopes intégrés

Scopes personnalisés

Définissez vos propres scopes sur la page Scopes. Chaque scope décrit une autorisation ou une ressource qu'un client peut demander (par exemple, billing.read, orders.write).

Claims personnalisés sur les jetons

Les claims personnalisés ont deux moitiés. La source est constituée de données par utilisateur : chaque AuthUser dispose d'un dictionnaire customAttributes que vous pouvez peupler depuis le Portal (Utilisateurs → utilisateur → Attributs personnalisés), via SCIM, ou via un hook de provisioning TCC. La libération est par scope : la liste userClaims de chaque scope nomme les clés autorisées à quitter le serveur.

Quand un client demande des scopes, Authagonal parcourt les scopes accordés, fait l'union de leurs listes userClaims et émet uniquement ces clés depuis les customAttributes de l'utilisateur. Les clés inconnues sont silencieusement ignorées — un client ne peut pas lire un attribut en devinant son nom. Les claims OIDC standard (sub, email, name, etc.) suivent la spécification et ne sont pas soumis à la whitelist.

# 1. On the user (Portal → Users → {user} → Custom Attributes)
department = "engineering"
employee_id = "E-1042"
seat_tier = "enterprise"

# 2. On a custom scope (Portal → Scopes → projects.read)
name        = "projects.read"
userClaims  = ["department", "seat_tier"]   # <-- whitelist

# 3. Client requests scope=openid projects.read
# Decoded access token (relevant fields only):
{
  "sub": "u-9b…",
  "scope": "openid projects.read",
  "department": "engineering",
  "seat_tier":  "enterprise"
  // employee_id is NOT emitted — it's not in the whitelist for any granted scope.
}

Attribuer des scopes aux clients

Ajoutez les scopes autorisés dans l'onglet Clients → Scopes et Grants. Un client ne peut demander que les scopes qui lui ont été accordés ; les scopes inconnus sont rejetés avec invalid_scope.

Personnalisation de marque

Personnalisez l'apparence des pages de connexion de votre tenant. Les parametres de personnalisation vous permettent d'adapter l'experience d'authentification a l'identite visuelle de votre produit -- des logos et couleurs aux remplacements CSS avances.

Apparence

Parametres d'apparence avec apercu des couleurs en direct

Informations de contact

Options de la page de connexion

Controlez les elements qui apparaissent sur la page de connexion de votre tenant :

Exemple de page de connexion avec personnalisation de marque appliquee

CSS personnalisé

Pour un contrôle total sur l'apparence de la page de connexion, fournissez une URL de fichier CSS dans vos paramètres de charte graphique. Le fichier est chargé après les styles par défaut, vos règles prennent donc le pas.

Mode sombre

L'application de connexion propose des thèmes clair, sombre et système. Les utilisateurs choisissent via un bouton bascule sur la page de connexion ; le choix est conservé entre les sessions. En mode system, la SPA suit prefers-color-scheme en temps réel.

Les valeurs claires sont déclarées dans :root ; les remplacements sombres sont limités à .dark. Le branding du tenant via customCssUrl prévaut toujours — vos couleurs sont préservées quel que soit le thème choisi par l'utilisateur.

Parametres

Configurez les politiques de securite, les webhooks et les parametres d'environnement a l'echelle du tenant. Ces parametres s'appliquent globalement a tous les clients sauf s'ils sont remplaces au niveau du client.

Politique de mot de passe

Definissez les exigences de complexite des mots de passe pour tous les utilisateurs de votre tenant :

Configuration de la politique de mot de passe

Politique MFA

La politique MFA a l'echelle du tenant definit le comportement par defaut de l'authentification multi-facteurs. Les clients individuels peuvent remplacer ce parametre.

Session et verrouillage

Controlez la duree des sessions et le comportement de verrouillage des comptes :

Configuration de la session et du verrouillage

Webhooks

Les webhooks vous permettent de réagir aux événements d'authentification en temps réel. Deux événements (onUserAuthenticated, onTokenIssued) sont applicables — par défaut ils se déclenchent de manière asynchrone et ne bloquent pas l'utilisateur, mais vous pouvez activer l'application par événement pour qu'une réponse non 2xx ou un corps {"allow": false} rejette l'action. Les autres événements sont des notifications — toujours fire-and-forget, ne bloquent jamais.

Parametres de webhook supplementaires :

Configuration des evenements webhook

Vérifier les webhooks

Une fois qu'une URL de webhook est configurée, Authagonal génère un secret de signature propre au tenant (une valeur whsec_… affichée en lecture seule dans Paramètres → Webhooks). Chaque livraison sortante porte un en-tête X-Authagonal-Signature: t=<unix>,v1=<hex>, où v1 vaut HMAC-SHA256(secret, "{t}.{body}") calculé sur le corps brut de la requête. Recalculez-le sur votre point de terminaison et comparez en temps constant pour confirmer que la requête provient réellement d'Authagonal et n'a pas été altérée — et rejetez les livraisons dont le t est trop ancien afin de bloquer les rejeux.

import crypto from 'node:crypto';

// rawBody MUST be the exact bytes Authagonal sent — verify before any JSON re-serialization.
function verifyAuthagonalWebhook(signatureHeader, rawBody, signingSecret) {
  const parts = Object.fromEntries(signatureHeader.split(',').map((p) => p.split('=')));
  const { t, v1 } = parts;

  // Replay protection: reject deliveries older than 5 minutes.
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  return v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Fenetre de maintenance

Definissez une fenetre de maintenance preferee pour les operations perturbantes telles que les rotations de certificats et les mises a jour d'infrastructure. Choisissez une heure UTC (0-23) -- le portail affiche egalement l'heure equivalente dans votre fuseau horaire local pour plus de commodite.

Environnement bac a sable

L'environnement bac a sable est un clone complet de votre tenant de production, disponible a une URL separee. Utilisez-le pour tester les modifications de configuration, les integrations SSO et les points de terminaison webhook sans affecter les utilisateurs en direct.

Le bac a sable est accessible a {slug}-sandbox.authagonal.io.

Controles de l'environnement bac a sable

Facturation

Gerez votre abonnement et votre facturation via la page Facturation du portail. Cette page vous donne un apercu de votre plan actuel et fournit l'acces au portail de facturation Stripe pour gerer les moyens de paiement, les factures et les changements de plan.

Informations d'abonnement

La page de facturation affiche les details de votre abonnement actuel en un coup d'oeil. Vous verrez un badge de statut indiquant l'etat de votre abonnement -- active, trialing, past_due, canceled ou unpaid -- ainsi que le nom de votre plan, la periode de facturation actuelle (dates de debut et de fin), et si votre abonnement est configure pour s'annuler a la fin de la periode en cours.

Gerer l'abonnement

Cliquez sur le bouton Gerer l'abonnement pour ouvrir le portail de facturation Stripe dans une nouvelle fenetre. De la, vous pouvez mettre a jour vos moyens de paiement, consulter et telecharger les factures, changer de plan ou annuler votre abonnement.

Si aucun abonnement n'existe encore, un bouton Configurer la facturation est affiche a la place, qui vous guide dans le choix d'un plan et la saisie des informations de paiement.

La page de facturation affiche les details de votre abonnement actuel et fournit l'acces a Stripe

Domaines personnalises

Servez vos pages d'authentification depuis votre propre domaine (par ex. auth.votredomaine.com) au lieu du domaine par defaut {slug}.authagonal.io. Les domaines personnalises offrent a vos utilisateurs une experience d'authentification transparente et personnalisee.

Ajouter un domaine

Entrez le nom d'hote que vous souhaitez utiliser dans le formulaire d'ajout de domaine (par ex. auth.votredomaine.com). Une fois ajoute, le domaine apparaitra dans votre liste de domaines avec le statut pending_verification.

Verification DNS

Creez un enregistrement CNAME pointant votre domaine vers {slug}.authagonal.io. Une fois l'enregistrement DNS en place, cliquez sur Verifier pour controler la propagation DNS.

auth.yourdomain.com.  CNAME  acme.authagonal.io.

Certificats TLS

Une fois votre domaine verifie, vous avez besoin d'un certificat TLS pour que les utilisateurs puissent se connecter en toute securite via HTTPS. Authagonal prend en charge deux options :

Automatique (cert-manager) -- Authagonal provisionne et renouvelle automatiquement les certificats TLS avec cert-manager. C'est l'option recommandee pour la plupart des utilisateurs. Aucune configuration supplementaire n'est requise.

Apportez le votre (BYO) -- Telechargez votre propre certificat et cle privee au format PEM. Cette option est utile si votre organisation exige des certificats d'une autorite de certification specifique. L'expiration du certificat est suivie pour que vous puissiez le renouveler avant qu'il n'expire.

Statut du domaine

Chaque domaine affiche un badge de statut indiquant son etat actuel : pending_verification (DNS non encore confirme), verified (DNS confirme, TLS en attente), active (entierement operationnel) ou failed (probleme de configuration detecte).

La liste des domaines affiche chaque domaine personnalise et son statut actuel

Telechargez votre propre certificat TLS et cle privee au format PEM

Configuration des e-mails

Configurez la façon dont votre tenant envoie les e-mails transactionnels — vérification, réinitialisation de mot de passe et notifications MFA. Choisissez entre l'expéditeur partagé par défaut, un domaine personnalisé vérifié via Resend, ou votre propre serveur SMTP.

Fournisseurs d'e-mails

Identité de l'expéditeur

L'e-mail et le nom de l'expéditeur sont partagés entre tous les modes de fournisseur. L'e-mail de l'expéditeur est requis ; à défaut, le nom revient à celui du tenant.

Domaine personnalisé Resend

Vérifiez votre domaine d'envoi auprès de Resend une seule fois, puis utilisez-le comme adresse d'expéditeur pour ce tenant. Les enregistrements DNS TXT (SPF, DKIM) sont fournis par la page Domaines ; Resend les valide automatiquement.

SMTP personnalisé

Apportez votre propre serveur SMTP — utile pour les relais internes, les prestataires non pris en charge par Resend, ou la conformité réglementaire.

Domaine d'envoi personnalisé

Avec le fournisseur Resend, vous pouvez enregistrer votre propre domaine pour que les e-mails proviennent de votre marque (par ex. noreply@acme.com) au lieu de @authagonal.io.

1. Allez dans Paramètres → E-mail et sélectionnez le fournisseur Domaine personnalisé Resend.
2. Saisissez votre nom de domaine et cliquez sur Enregistrer.
3. Ajoutez les enregistrements DNS affichés (DKIM, SPF et return path) au DNS de votre domaine.
4. Cliquez sur Vérifier la vérification — une fois le DNS propagé (généralement 1 à 10 minutes), le statut du domaine passera à vérifié.

Tests

Utilisez le bouton Envoyer un e-mail de test dans Paramètres → E-mail pour vérifier votre configuration. Un e-mail de test sera envoyé à votre adresse d'administrateur avec les paramètres enregistrés.

Journal d'audit

Le journal d'audit fournit un enregistrement en lecture seule de toutes les actions administratives effectuees sur votre tenant. Chaque modification effectuee via le portail ou l'API est capturee avec un contexte complet, vous offrant une piste complete pour la conformite et le depannage.

Colonnes du journal

Actions suivies

Les actions administratives suivantes sont enregistrees dans le journal d'audit :

Le journal d'audit fournit un enregistrement complet de toutes les actions administratives

Sauvegardes

Authagonal sauvegarde automatiquement les données de votre tenant toutes les heures. Les sauvegardes incluent tous les utilisateurs, groupes, rôles, clients, connexions SSO, jetons SCIM, la charte graphique et les paramètres. Vous pouvez consulter l'historique et télécharger la dernière sauvegarde complète depuis la page Sauvegardes.

Fonctionnement des sauvegardes

• Une sauvegarde complète s'exécute une fois par jour, capturant chaque table du shard de stockage de votre tenant.
• Les sauvegardes incrémentielles s'exécutent toutes les heures, ne capturant que les lignes modifiées depuis la dernière sauvegarde.
• Les sauvegardes sont stockées dans Azure Blob Storage avec la même identité gérée que celle de votre tenant.
• Les enregistrements supprimés sont suivis via des tombstones et inclus dans les sauvegardes à des fins d'audit.

Téléchargement des sauvegardes

Cliquez sur « Télécharger la dernière » pour obtenir un fichier ZIP contenant la sauvegarde complète la plus récente fusionnée avec toutes les sauvegardes incrémentielles suivantes. Chaque table est exportée en fichier JSONL (un objet JSON par ligne).

Applications de provisionnement

Les applications de provisionnement recoivent des notifications webhook en temps reel lorsque des utilisateurs sont crees ou authentifies dans votre tenant. Cela permet aux systemes en aval de configurer automatiquement des comptes, d'attribuer des licences ou de synchroniser les donnees utilisateur sans intervention manuelle.

Comment ca fonctionne

Lorsqu'un evenement utilisateur se produit (creation ou authentification), Authagonal appelle l'URL de rappel de votre application de provisionnement en utilisant le modele TCC (Try/Confirm/Cancel). Cette approche en trois phases garantit un provisionnement fiable a travers plusieurs systemes en aval :

Payload du webhook

Chaque requete webhook inclut un payload JSON avec les champs suivants :

Ajouter une application de provisionnement

Pour ajouter une application de provisionnement, fournissez un nom, une URL de rappel et une cle API optionnelle. La cle API est envoyee en tant que jeton Bearer dans l'en-tete Authorization de chaque requete webhook, permettant a votre application d'authentifier les requetes provenant d'Authagonal.

Test

Cliquez sur Tester a cote de n'importe quelle application de provisionnement pour envoyer une requete de test a votre URL de rappel. Les resultats du test affichent le code de statut HTTP et le corps de la reponse, vous aidant a verifier que votre application recoit et traite correctement les webhooks.

Testez les applications de provisionnement pour verifier la livraison et le traitement des webhooks

Limites du plan

Le nombre maximum d'applications de provisionnement est configurable par tenant, avec une limite par defaut de 6. Cette limite peut etre ajustee par un administrateur si votre workflow necessite des cibles de provisionnement supplementaires.

Equipe

La page Equipe gere les administrateurs du portail -- les personnes qui peuvent acceder a votre tenant et le configurer via le portail de gestion. Tous les membres de l'equipe ont un acces administratif complet a chaque aspect de la configuration de votre tenant.

Liste des administrateurs

La liste des administrateurs affiche le nom, l'adresse e-mail et la date d'ajout de chaque membre de l'equipe. Un indicateur "Vous" est affiche a cote de la ligne de l'utilisateur actuel pour que vous puissiez facilement identifier votre propre compte.

Inviter des administrateurs

Pour inviter un nouveau membre de l'equipe, fournissez son adresse e-mail, son nom et un mot de passe temporaire (minimum 8 caracteres). L'utilisateur invite se connecte avec le mot de passe temporaire et devrait le changer lors de sa premiere connexion.

Champs d'invitation

Les invitations d'administrateur créent un utilisateur entièrement provisionné — pas d'aller-retour par e-mail requis.

Supprimer des administrateurs

Cliquez sur Supprimer a cote de n'importe quel membre de l'equipe pour revoquer son acces. Une boite de dialogue de confirmation s'affiche avant que la suppression ne soit finalisee. Vous ne pouvez pas vous supprimer vous-meme -- il doit toujours y avoir au moins un administrateur dans l'equipe.

Gerez les administrateurs du portail depuis la page Equipe

Importer et migrer

Migrez un système d’identité existant vers votre tenant Authagonal. Deux sources sont prises en charge — Duende IdentityServer (une base SQL Server) et Auth0 (la Management API). Chacune exécute un aperçu en lecture seule pour que vous vérifiiez exactement ce qui sera copié avant de valider.

Importation depuis Duende IdentityServer

Migrez les clients, scopes, utilisateurs et rôles d'une base SQL Server Duende IdentityServer existante vers votre tenant Authagonal. L'importation se déroule en deux phases — aperçu et validation — afin que vous puissiez vérifier ce qui sera copié avant toute modification.

Ce qui est importé

L'importateur lit la ConfigurationDb de Duende et les tables ASP.NET Identity, puis écrit les lignes mappées dans votre tenant. Les artefacts à courte durée de vie (persisted grants, device codes, clés de signature) sont ignorés.

Aperçu avant validation

Collez votre chaîne de connexion ConfigurationDb / IdentityDb de Duende puis cliquez sur Lancer l'aperçu. L'aperçu ouvre une connexion en lecture seule et compte chaque ligne qui serait importée — aucune écriture n'a lieu.

• Décomptes d'entités pour clients, scopes, utilisateurs, rôles et affectations de rôles.
• Collisions de propriétaires — administrateurs du tenant dont le <code>userId</code> existant diffère du <code>sub</code> Duende entrant.
• Avertissements pour les tables inconnues et colonnes non mappées afin que vous sachiez ce qui sera abandonné.

Panneau d'aperçu avec décomptes, collisions et avertissements

Empreintes de mot de passe

Duende stocke les mots de passe au format ASP.NET Identity V3 (PBKDF2). Le PasswordHasher d'Authagonal vérifie directement ce format et réhash vers le format natif à la première connexion réussie — les utilisateurs conservent leur mot de passe existant sans flux de réinitialisation.

Rotation du userId propriétaire

Si l'e-mail d'un administrateur du tenant correspond à un utilisateur dans la base Duende, le userId Authagonal de cet admin est aligné sur le sub Duende. Cela maintient la cohérence des tokens et des entrées d'audit après la bascule. L'aperçu liste chaque collision avant la validation.

Exécuter l'importation

Cliquez sur Démarrer l'import après avoir vérifié l'aperçu. La phase de validation écrit les clients, scopes, utilisateurs, rôles et références de connexion externe dans les stores de votre tenant. Les lignes en doublon de clientId, scope name, email et role name sont ignorées — l'importateur peut être relancé sans risque.

Ce qui n'est pas importé

• Persisted grants, device codes, sessions côté serveur — courte durée de vie, régénérés automatiquement.
• Clés de signature — Authagonal émet ses propres clés par tenant.
• Colonnes et tables personnalisées — tout ce qui dépasse le schéma standard de Duende remonte en avertissement afin que vous sachiez que ces données sont abandonnées.
• Clients désactivés — importés à l'état désactivé ; réactivez-les depuis la page Clients quand vous êtes prêt.

Importer depuis Auth0

Connectez Authagonal à la Management API de votre tenant Auth0 et transférez vos applications, APIs, rôles, utilisateurs et connexions d’entreprise. Les identifiants d’utilisateur et d’application importés sont conservés, de sorte que les références sub et client_id existantes continuent de se résoudre après la bascule.

Ce dont vous aurez besoin

Créez une application Machine-to-Machine dans Auth0 autorisée pour la Management API, avec ces scopes de lecture : read:users, read:clients, read:resource_servers, read:roles, read:connections, read:client_grants. Collez son domaine, son client ID et son client secret dans le formulaire d’import — ils ne servent qu’à l’import.

Ce qui est importé

Mots de passe

La Management API d’Auth0 ne renvoie jamais les empreintes de mot de passe. Si vous disposez de l’export groupé de mots de passe assisté par le support Auth0 (NDJSON), fournissez-le — les empreintes bcrypt sont importées telles quelles et vos utilisateurs conservent leur mot de passe sans réinitialisation. Ce fichier contient aussi l’intégralité de vos utilisateurs, levant la limite de 1 000 utilisateurs du listing de l’API Auth0. Sans lui, les utilisateurs sont importés sous forme de profils et définissent un nouveau mot de passe à la première connexion.

Reference API

Chaque tenant expose un serveur OIDC conforme aux standards a l'adresse https://{slug}.authagonal.io. Tous les points de terminaison suivent les specifications OAuth 2.0 et OpenID Connect. Cette reference couvre chaque point de terminaison avec lequel votre application peut avoir besoin d'interagir.

Flux Authorization Code avec PKCE

Decouverte OIDC & JWKS

Le document de decouverte permet aux bibliotheques clientes OIDC de se configurer automatiquement. Aucune authentification n'est requise pour ces points de terminaison.

GET /.well-known/openid-configuration

Renvoie le document de configuration du fournisseur OpenID. La reponse inclut toutes les metadonnees dont votre client a besoin pour interagir avec ce tenant.

GET /.well-known/openid-configuration/jwks

Renvoie le JSON Web Key Set utilise pour verifier les signatures de jetons. La reponse contient un tableau keys avec des cles publiques RSA, chacune incluant les champs kty, use, kid, alg, n et e.

curl https://acme.authagonal.io/.well-known/openid-configuration

Point de terminaison d'autorisation

GET /connect/authorize

Initie un flux authorization code. L'utilisateur doit avoir une session active ou il sera redirige vers la page de connexion. En cas de succes, l'utilisateur est redirige vers votre application avec un code d'autorisation.

Reponse de succes : Redirection 302 vers redirect_uri avec les parametres de requete code et state.

Reponse d'erreur : Redirection 302 avec les parametres de requete error, error_description et state.

Pushed Authorization Requests (PAR)

RFC 9126. Au lieu de placer chaque paramètre d'autorisation dans l'URL, votre client les envoie par POST à /connect/par avec une authentification client classique et reçoit en retour une request_uri opaque et de courte durée. Le navigateur visite ensuite /connect/authorize?client_id=...&request_uri=... — rien d'autre n'apparaît dans l'historique du navigateur, les logs du serveur ou les en-têtes Referer, et le serveur a déjà vérifié l'intégrité des paramètres sous authentification du client.

POST /connect/par

L'authentification client est la même que pour /connect/token : HTTP Basic avec client_id/client_secret, ou identifiants encodés dans le formulaire. Les clients publics publient sans secret. Le corps porte les mêmes paramètres que vous enverriez normalement à /connect/authorize ; request_uri lui-même est rejeté (chaîner un PAR est interdit par §2.1 de la spec). Renvoie 201 Created.

Réponse

Sur l'appel suivant GET /connect/authorize?client_id=…&request_uri=…, tous les autres paramètres sont extraits de la charge utile poussée et tout paramètre de requête supplémentaire est ignoré. Le client_id de l'appel d'autorisation doit correspondre au client qui a poussé la requête. Une fois consommée (ou une fois expires_in écoulé), la request_uri est retirée du stockage.

# 1. Push parameters (server returns request_uri + expires_in)
curl -X POST https://acme.authagonal.io/connect/par \
  -u "my-app:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "response_type=code" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "scope=openid profile email" \
  -d "state=$(openssl rand -hex 16)" \
  -d "code_challenge=YOUR_CODE_CHALLENGE" \
  -d "code_challenge_method=S256"

# 2. Send the user to /authorize with only client_id + request_uri
# https://acme.authagonal.io/connect/authorize?client_id=my-app&request_uri=urn:ietf:params:oauth:request_uri:abc123...

Point de terminaison de jeton

POST /connect/token

Echange des identifiants contre des jetons. Les requetes doivent utiliser Content-Type: application/x-www-form-urlencoded. L'authentification client peut etre fournie via HTTP Basic auth (Authorization: Basic base64(client_id:client_secret)) ou comme parametres dans le corps du formulaire (client_id + client_secret).

Grant Authorization Code

Grant Refresh Token

Grant Client Credentials

Grant Device Code

Reponse de jeton :

curl -X POST https://acme.authagonal.io/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "client_id=my-app" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

Point de terminaison UserInfo

GET /connect/userinfo

Renvoie les claims concernant l'utilisateur authentifie. Necessite un jeton d'acces valide avec le scope openid.

curl https://acme.authagonal.io/connect/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

Introspection de jeton (RFC 7662)

POST /connect/introspect

Valide un jeton et renvoie ses metadonnees. Necessite des identifiants client (Basic auth ou parametres dans le corps du formulaire).

Reponse de jeton actif :

Reponse de jeton inactif : { "active": false }

curl -X POST https://acme.authagonal.io/connect/introspect \
  -u "my-app:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=ACCESS_OR_REFRESH_TOKEN"

Revocation de jeton (RFC 7009)

POST /connect/revocation

Revoque un jeton precedemment emis. Necessite des identifiants client.

Le point de terminaison renvoie toujours 200 OK, meme pour les jetons invalides ou deja revoques, conformement a la specification RFC 7009.

Autorisation d'appareil (RFC 8628)

POST /connect/deviceauthorization

Initie le flux d'autorisation d'appareil pour les appareils a saisie limitee (CLI, smart TV, appareils IoT). L'appareil affiche un code a l'utilisateur, qui approuve ensuite la requete sur un appareil separe disposant d'un navigateur.

Reponse :

Flux d'approbation : L'utilisateur visite la verification_uri, entre le user_code et approuve la requete. Pendant ce temps, l'appareil interroge le point de terminaison de jeton avec le device_code.

Codes d'erreur de polling :

curl -X POST https://acme.authagonal.io/connect/deviceauthorization \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=my-cli" \
  -d "scope=openid profile email"

Fin de session / Deconnexion

GET POST /connect/endsession

Deconnecte la session utilisateur actuelle, declenche la deconnexion back-channel vers tous les clients avec un BackChannelLogoutUri enregistre, et revoque tous les grants.

Si un post_logout_redirect_uri valide est fourni et correspond a une URI enregistree, l'utilisateur recoit une redirection 302. Sinon, une reponse JSON confirme que la session a ete terminee.

Reference API SCIM 2.0

Authagonal prend en charge le protocole SCIM 2.0 pour le provisionnement automatise des utilisateurs et des groupes. Les fournisseurs d'identite tels qu'Okta, Azure AD et OneLogin peuvent utiliser cette API pour maintenir votre tenant Authagonal synchronise avec votre annuaire d'entreprise.

URL de base : https://{slug}.authagonal.io/scim/v2

Authentification : Toutes les requetes necessitent un jeton Bearer. Generez un jeton SCIM dans le portail sous Parametres > Provisionnement SCIM.

En-tetes communs :

Les points de terminaison de liste prennent en charge la pagination via les parametres de requete startIndex (base 1) et count (max 200), et le filtrage via le parametre filter (par ex. userName eq "user@example.com").

Utilisateurs

GET /scim/v2/Users — Lister les utilisateurs avec pagination et filtrage optionnels.

GET /scim/v2/Users/{id} — Obtenir un utilisateur unique par son identifiant utilisateur Authagonal.

POST /scim/v2/Users — Creer un nouvel utilisateur. Renvoie 201 Created.

PUT /scim/v2/Users/{id} — Remplacement complet d'une ressource utilisateur. Tous les champs doivent etre fournis.

PATCH /scim/v2/Users/{id} — Mise a jour partielle utilisant SCIM PatchOp.

DELETE /scim/v2/Users/{id} — Supprime l'utilisateur de maniere logique (desactive le compte et revoque tous les jetons). Renvoie 204 No Content.

curl -X POST https://acme.authagonal.io/scim/v2/Users \
  -H "Authorization: Bearer SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "jane@acme.com",
    "name": {
      "givenName": "Jane",
      "familyName": "Smith"
    },
    "displayName": "Jane Smith",
    "active": true,
    "externalId": "ext-12345"
  }'

Groupes

GET /scim/v2/Groups — Lister tous les groupes avec pagination et filtrage optionnels.

GET /scim/v2/Groups/{id} — Obtenir un groupe unique par ID, y compris sa liste de membres.

POST /scim/v2/Groups — Creer un nouveau groupe. Renvoie 201 Created.

PUT /scim/v2/Groups/{id} — Remplacement complet d'une ressource de groupe (y compris sa liste de membres).

PATCH /scim/v2/Groups/{id} — Mise a jour partielle pour ajouter ou supprimer des membres du groupe.

DELETE /scim/v2/Groups/{id} — Supprime definitivement le groupe. Renvoie 204 No Content.

curl -X PATCH https://acme.authagonal.io/scim/v2/Groups/GROUP_ID \
  -H "Authorization: Bearer SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "add",
        "path": "members",
        "value": [
          { "value": "USER_ID_1" },
          { "value": "USER_ID_2" }
        ]
      }
    ]
  }'

API du portail (automatisation)

L'API du portail permet a votre propre backend d'automatiser tout ce que vous pouvez faire dans le portail -- gerer les utilisateurs, les clients, les groupes, les roles, les scopes, les connexions SSO et les parametres -- a l'aide d'un identifiant machine a machine. Il s'agit de la meme API que celle appelee par l'interface du portail.

URL de base : https://portal-api.<your-domain>/api/v1. Les requetes s'authentifient avec un jeton d'acces Bearer ; le tenant est determine a partir du jeton, et non de l'URL.

Creer un identifiant d'API

Dans le portail, ouvrez Clients → Create API credential, choisissez un niveau d'acces et donnez-lui un nom. Authagonal genere un client OAuth client_credentials configure pour l'API du portail et renvoie un ID client et un secret.

Niveaux d'acces

Obtenir un jeton

Echangez l'identifiant contre un jeton d'acces au point de terminaison de jeton de votre tenant administratif -- https://<your-tenant>.<your-domain>/connect/token -- puis envoyez le jeton dans un en-tete Bearer a l'API du portail. Les jetons sont valides pendant une heure.

# 1. Exchange the credential for an access token (your tenant's token endpoint)
curl -X POST https://acme.authagonal.io/connect/token \
  -d grant_type=client_credentials \
  -d client_id=api-3f2a... \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d scope=tenant:admin

# Response: { "access_token": "ey...", "token_type": "Bearer", "expires_in": 3600 }

# 2. Call the Portal API with the access token
curl https://portal-api.authagonal.io/api/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Points de terminaison

Tous les chemins sont relatifs à l'URL de base et nécessitent un jeton d'accès Bearer. Le scope indiqué à côté de chaque groupe correspond au niveau d'accès minimal requis pour les identifiants. Les endpoints de liste acceptent les paramètres de requête startIndex et count.

GET/api/v1/clients— Lister les clients OAuth.

GET/api/v1/clients/{id}— Récupérer un client par son ID.

POST/api/v1/clients— Créer un client. Renvoie l'ID du client et, pour les clients confidentiels, un secret à usage unique.

PUT/api/v1/clients/{id}— Mettre à jour un client (URI de redirection, types d'autorisation, durées de vie des jetons, exigences PKCE/PAR).

DELETE/api/v1/clients/{id}— Supprimer un client.

POST/api/v1/clients/api-credential— Générer un identifiant d'API Portal machine-to-machine.

GET/api/v1/users— Lister les utilisateurs. Prend en charge startIndex, count et search (préfixe e-mail / nom).

GET/api/v1/users/count— Nombre total d'utilisateurs du locataire.

GET/api/v1/users/stats/mfa— Statistiques d'inscription à la MFA.

GET/api/v1/users/{id}— Récupérer un utilisateur.

POST/api/v1/users— Créer un utilisateur avec un e-mail et un mot de passe.

PUT/api/v1/users/{id}— Mettre à jour un utilisateur (profil, e-mail, état activé/bloqué).

DELETE/api/v1/users/{id}— Supprimer un utilisateur.

GET/api/v1/users/{id}/mfa— Get a user's enrolled MFA methods.

DELETE/api/v1/users/{id}/mfa— Reset a user's MFA enrollment.

GET/api/v1/roles— Lister les rôles.

POST/api/v1/roles— Créer un rôle.

DELETE/api/v1/roles/{id}— Supprimer un rôle.

POST/api/v1/roles/assign— Attribuer un rôle à un utilisateur.

POST/api/v1/roles/unassign— Retirer un rôle à un utilisateur.

GET/api/v1/groups— Lister les groupes.

GET/api/v1/groups/{id}— Récupérer un groupe et ses membres.

POST/api/v1/groups— Créer un groupe.

POST/api/v1/groups/{id}/members— Ajouter des membres à un groupe.

DELETE/api/v1/groups/{groupId}/members/{userId}— Retirer un membre d'un groupe.

DELETE/api/v1/groups/{id}— Supprimer un groupe.

GET/api/v1/group-role-mappings— Lister les correspondances groupe-rôle (rôles accordés à l'émission du jeton selon l'appartenance au groupe).

GET/api/v1/scopes— Lister les scopes d'API.

POST/api/v1/scopes— Créer un scope.

DELETE/api/v1/scopes/{name}— Supprimer un scope.

GET/api/v1/saml/connections— Lister les connexions SAML.

POST/api/v1/saml/connections— Créer une connexion SAML.

DELETE/api/v1/saml/connections/{id}— Supprimer une connexion SAML.

GET/api/v1/oidc/connections— Lister les connexions OIDC.

POST/api/v1/oidc/connections— Créer une connexion OIDC.

DELETE/api/v1/oidc/connections/{id}— Supprimer une connexion OIDC.

GET/api/v1/sso/domains— Lister les domaines routés vers les connexions SSO (découverte du domaine d'origine).

GET/api/v1/branding— Récupérer la personnalisation du locataire (couleurs, logo, langues prises en charge).

PUT/api/v1/branding— Mettre à jour la personnalisation du locataire.

GET/api/v1/settings— Récupérer les paramètres du locataire (webhooks, inscription publique, politique de jetons).

PUT/api/v1/settings— Mettre à jour les paramètres du locataire.

POST/api/v1/settings/webhook-secret/regenerate— Faire pivoter le secret de signature des webhooks.

POST/api/v1/settings/test-email— Envoyer un e-mail de test avec la configuration e-mail actuelle.

GET/api/v1/custom-domains— Lister les domaines de connexion personnalisés et leur statut de vérification.

POST/api/v1/custom-domains— Ajouter un domaine personnalisé.

POST/api/v1/custom-domains/{domain}/verify— Déclencher la vérification DNS d'un domaine personnalisé.

DELETE/api/v1/custom-domains/{domain}— Supprimer un domaine personnalisé.

GET/api/v1/email/domains— Lister les domaines e-mail d'expéditeur.

GET/api/v1/audit— Interroger le journal d'audit du locataire.

Exemple : créer un utilisateur

curl -X POST https://portal-api.authagonal.io/api/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@acme.com",
    "password": "S3cure-temp-passw0rd",
    "firstName": "Ada",
    "lastName": "Lovelace"
  }'

# 200 OK
# { "userId": "8f3a...", "email": "ada@acme.com" }

Flux d'authentification

Les flux d'authentification couvrent la maniere dont les utilisateurs finaux interagissent avec votre tenant Authagonal -- connexion, inscription, reinitialisation de mot de passe et configuration de la MFA. Ces points de terminaison sont utilises par la page de connexion hebergee et peuvent etre appeles directement si vous construisez une interface de connexion personnalisee.

Connexion

POST /api/auth/login

Authentifie un utilisateur avec un e-mail et un mot de passe. En cas de succes, signe un cookie de session et renvoie le profil utilisateur. Si la MFA est configuree, la reponse indique qu'un second facteur est requis avant que la session ne soit completement etablie.

Corps de la requete :

{
  "email": "user@example.com",
  "password": "correct-horse-battery-staple"
}

Reponse de succes :

Reponse MFA requise : Lorsque l'utilisateur a la MFA inscrite, la reponse inclut mfaRequired: true ainsi qu'un challengeId et un tableau methods listant les methodes MFA disponibles.

Reponse de configuration MFA requise : Lorsque le tenant exige la MFA mais que l'utilisateur ne s'est pas encore inscrit, la reponse inclut mfaSetupRequired: true avec un setupToken pour le flux d'inscription.

Reponses d'erreur :

Verification SSO : Si le domaine d'e-mail de l'utilisateur a une connexion SSO configuree, le point de terminaison de connexion renvoie sso_required avec une redirectUrl. Le client doit rediriger l'utilisateur vers le fournisseur SSO.

Verrouillage de compte : Apres maxFailedAttempts tentatives de connexion echouees consecutives, le compte est verrouille pendant lockoutDurationMinutes. Les deux valeurs sont configurables dans les parametres du tenant.

Inscription

POST /api/auth/register

Cree un nouveau compte utilisateur. Un e-mail de verification est envoye automatiquement -- l'utilisateur doit verifier son e-mail avant de pouvoir se connecter.

Corps de la requete :

{
  "email": "newuser@example.com",
  "password": "a-strong-password-here",
  "firstName": "Jane",
  "lastName": "Smith"
}

Succes : 201 Created avec le userId du nouveau compte.

Reponses d'erreur :

Reinitialisation du mot de passe

POST /api/auth/forgot-password

Demande un e-mail de reinitialisation de mot de passe. Le point de terminaison renvoie toujours une reponse de succes, que l'e-mail existe ou non, pour empecher l'enumeration des e-mails.

{
  "email": "user@example.com"
}

POST /api/auth/reset-password

Reinitialise le mot de passe de l'utilisateur en utilisant le jeton provenant du lien dans l'e-mail.

{
  "token": "RESET_TOKEN_FROM_EMAIL",
  "newPassword": "new-strong-password"
}

Effets secondaires d'une reinitialisation de mot de passe reussie :

• Le compteur de tentatives de connexion echouees est remis a zero
• Tous les jetons de rafraichissement existants sont revoques
• Un nouveau tampon de securite est genere (invalidant toutes les sessions existantes)

Configuration et verification MFA

Authagonal prend en charge trois methodes MFA : TOTP (applications d'authentification), WebAuthn (cles de securite et biometrie) et codes de recuperation a usage unique.

Configuration TOTP

POST /api/auth/mfa/totp/setup — Renvoie un URI de donnees de QR code et une cle de saisie manuelle. L'utilisateur scanne le QR code avec son application d'authentification (Google Authenticator, Authy, 1Password, etc.), puis confirme l'inscription.

POST /api/auth/mfa/totp/confirm — Confirme l'inscription TOTP en validant un code a 6 chiffres provenant de l'application d'authentification.

{
  "code": "123456"
}

Configuration WebAuthn

POST /api/auth/mfa/webauthn/setup -- Renvoie les options de creation d'identifiants pour l'API WebAuthn. Le navigateur appelle navigator.credentials.create() avec ces options.

POST /api/auth/mfa/webauthn/confirm — Confirme l'inscription WebAuthn en soumettant la reponse d'attestation du navigateur.

Codes de recuperation

POST /api/auth/mfa/recovery/generate — Genere 10 codes de recuperation a usage unique de 8 caracteres. Chaque code peut etre utilise exactement une fois pour contourner la MFA.

Verification MFA

POST /api/auth/mfa/verify — Complete le defi MFA apres une connexion par mot de passe reussie.

Statut MFA

GET /api/auth/mfa/status — Renvoie les methodes MFA actuellement inscrites de l'utilisateur.

Flux de connexion SSO

Authagonal prend en charge les connexions SSO basees sur SAML 2.0 et OIDC. Le routage par domaine detecte automatiquement quel fournisseur SSO utiliser en fonction de l'adresse e-mail de l'utilisateur.

Verification SSO

GET /api/auth/sso-check?email=user@acme.com

Flux SAML

L'utilisateur est redirige vers GET /saml/{connectionId}/login qui envoie une SAML AuthnRequest au fournisseur d'identite. L'IdP authentifie l'utilisateur et renvoie une reponse SAML au point de terminaison Assertion Consumer Service (ACS). Authagonal valide l'assertion, cree ou met a jour l'utilisateur et signe un cookie de session.

Les metadonnees SAML pour configurer votre IdP sont disponibles a GET /saml/{connectionId}/metadata.

Flux OIDC

L'utilisateur est redirige vers GET /oidc/{connectionId}/login qui redirige vers le fournisseur d'identite en amont avec PKCE. Apres l'authentification de l'utilisateur, le callback a /oidc/callback echange le code d'autorisation, valide le jeton ID et cree ou met a jour l'utilisateur.

Provisionnement JIT : Les flux SAML et OIDC prennent en charge le provisionnement just-in-time. Si l'utilisateur n'existe pas encore dans le tenant, il est cree automatiquement a partir des claims du fournisseur d'identite. S'il existe deja, ses attributs de profil sont mis a jour pour correspondre aux dernieres valeurs du fournisseur.

Créer une interface de connexion personnalisée

Remplacez les écrans de connexion, d'inscription, de réinitialisation de mot de passe et de MFA hébergés par Authagonal par votre propre interface, pendant qu'Authagonal continue de gérer l'authentification, la MFA, le SSO, les sessions et l'émission de jetons. Deux approches : utiliser notre bibliothèque de composants React, ou appeler directement l'API d'authentification depuis n'importe quel framework. C'est une option à activer — activez d'abord Custom login UI dans les paramètres du tenant.

Prérequis : un domaine personnalisé sur votre racine

La session de connexion est un cookie first-party, votre interface et le serveur d'authentification Authagonal doivent donc partager un domaine enregistrable. Pointez un domaine d'authentification personnalisé vers Authagonal sur la même racine que celle de votre application — par ex. l'authentification sur login.acme.com, l'application sur app.acme.com. Le paramètre Custom login UI reste désactivé tant qu'aucun domaine personnalisé actif n'existe.

Ajoutez également l'origine de votre interface (par ex. https://app.acme.com) aux Allowed CORS origins de votre client OAuth — la même liste que celle définie pour l'échange de jetons.

React : @authagonal/login

npm i @authagonal/login fournit la logique d'authentification et l'interface dans un seul paquet — le même que celui sur lequel repose la connexion hébergée par Authagonal. Choisissez votre niveau :

• Application complète — intégrez App et personnalisez-la via le branding.
• Composer des pages — utilisez LoginPage, MfaChallengePage, ResetPasswordPage… dans votre propre mise en page.
• Primitives + logique — créez vos propres écrans avec AuthLayout/Button/Input et le client API (login, mfaVerify, forgotPassword, …).

import { AuthLayout, Input, Button, login, ApiRequestError } from '@authagonal/login';

function MyLogin() {
  async function onSubmit(email: string, password: string) {
    try {
      const res = await login({ email, password });        // POST /login (sets the session cookie)
      if (res.mfaRequired) {/* render your MFA step → mfaVerify(...) */}
      else window.location.href = res.returnUrl;            // hand off to /connect/authorize
    } catch (e) {
      if (e instanceof ApiRequestError) {/* show e.message */}
    }
  }
  return <AuthLayout>{/* your own markup + <Input/> <Button/> */}</AuthLayout>;
}

N'importe quel framework : appeler l'API d'authentification

Pas sur React ? Appelez directement les points de terminaison du flux d'authentification (sous /api/auth), puis basculez vers le flux OIDC standard /connect/authorize. Envoyez credentials: 'include' pour que le cookie de session soit stocké.

# 1. Authenticate (browser fetch — credentials:'include' so the session cookie is stored)
curl -i -X POST https://login.acme.com/api/auth/login \
  -H "Content-Type: application/json" \
  -H "Origin: https://app.acme.com" \
  --data '{"email":"jane@acme.com","password":"..."}'
# (handle {"mfaRequired":true} → POST /api/auth/mfa/verify, then continue)

# 2. Hand off to the OAuth flow — top-level navigation to the authorize endpoint with PKCE:
# https://login.acme.com/connect/authorize?client_id=my-app&redirect_uri=...&response_type=code
#   &scope=openid%20profile%20email&code_challenge=...&code_challenge_method=S256
# The session cookie (same-site) authenticates the user; you get back a code → exchange at /connect/token.

Plans et limites

Authagonal propose quatre niveaux de plan. Tous les plans incluent toutes les fonctionnalites -- la seule difference est la limite d'utilisateurs actifs mensuels (MAU) et la tarification des depassements.

Niveaux de plan

Utilisateurs actifs mensuels (MAU)

Un utilisateur actif mensuel est tout utilisateur unique qui s'authentifie avec succes au moins une fois pendant un mois de facturation. Les utilisateurs provisionnes via SCIM mais qui ne se sont pas connectes ne comptent pas dans votre total MAU.

Depassement -- Si votre plan prend en charge le depassement, les utilisateurs au-dela de la limite MAU sont factures au tarif par utilisateur indique dans le tableau des plans ci-dessus. Vous pouvez definir un plafond de depassement pour limiter votre depense maximale pour la periode de facturation.

Application -- Si votre plan ne prend pas en charge le depassement (Starter), les utilisateurs au-dela de la limite MAU ne peuvent pas se connecter jusqu'a la prochaine periode de facturation ou jusqu'a ce que vous passiez a un plan qui prend en charge le depassement.