Skip to Content

API Applications

Les applications dans Auris représentent des apps client ou des services qui s’intègrent avec la plateforme IAM — web apps, apps mobile, serveurs API, CLI et services machine-to-machine. Chaque application a un Client ID (toujours visible) et optionnellement un Client Secret (pour les clients confidentiels). Auris supporte quatre types d’application : WEB, MOBILE, API et M2M.

Tous les endpoints de cette section nécessitent la permission manage:applications et le header x-tenant.

CRUD Applications

GET/api/applicationsRequires: manage:applications

Liste toutes les applications enregistrées dans le tenant. Retourne les informations de résumé pour chaque application incluant le type, le Client ID, les URI de redirect autorisés et la date de création.

Paramètres de query

ParamètreTypeDescription
pageintegerNuméro de page (défaut : 1)
limitintegerÉléments par page (défaut : 20)
typeWEB | MOBILE | API | M2MFiltre par type d’application
searchstringRecherche par nom d’application

Réponse de succès

{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "app_abc123",
        "name": "Mon Application Web",
        "type": "WEB",
        "clientId": "cid_abc123",
        "redirectUris": ["https://app.votredomaine.com/callback"],
        "allowedOrigins": ["https://app.votredomaine.com"],
        "createdAt": "2025-01-10T08:00:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 3, "totalPages": 1 }
  }
}
POST/api/applicationsRequires: manage:applications

Crée une nouvelle application. Pour les types WEB et MOBILE, les redirectUris doivent être fournis. Pour le type M2M, les redirectUris ne sont pas requis mais les scopes M2M doivent être configurés séparément. Un clientSecret est généré automatiquement et retourné uniquement dans la réponse de création — conserve-le en sécurité. Il ne peut pas être récupéré à nouveau ; utilise la rotation des secrets pour en générer un nouveau.

Corps de la requête

{
  "name": "Mon Dashboard",
  "type": "WEB",
  "redirectUris": [
    "https://app.votredomaine.com/callback",
    "http://localhost:3000/callback"
  ],
  "allowedOrigins": [
    "https://app.votredomaine.com",
    "http://localhost:3000"
  ]
}

Réponse de succès

{
  "ok": true,
  "data": {
    "id": "app_def456",
    "name": "Mon Dashboard",
    "type": "WEB",
    "clientId": "cid_def456",
    "clientSecret": "cs_sk_...",
    "redirectUris": ["https://app.votredomaine.com/callback", "http://localhost:3000/callback"],
    "allowedOrigins": ["https://app.votredomaine.com", "http://localhost:3000"],
    "createdAt": "2025-02-18T12:00:00Z"
  }
}

Le clientSecret est retourné une seule fois au moment de la création. Sauvegarde-le immédiatement. Pour les clients publics (SPA browser et apps mobile), n’utilise pas le clientSecret — utilise PKCE à la place.

Codes d’erreur

CodeHTTPDescription
NAME_TAKEN409Une application avec ce nom existe déjà
VALIDATION_ERROR400Format d’URI de redirect invalide ou champ obligatoire manquant
GET/api/applications/[id]Requires: manage:applications

Obtient les détails complets d’une seule application, incluant tous les champs de configuration. Le clientSecret n’est jamais retourné après la création — utilise la rotation pour en générer un nouveau.

Réponse de succès

{
  "ok": true,
  "data": {
    "id": "app_abc123",
    "name": "Mon Application Web",
    "type": "WEB",
    "clientId": "cid_abc123",
    "redirectUris": ["https://app.votredomaine.com/callback"],
    "allowedOrigins": ["https://app.votredomaine.com"],
    "enableDeviceFlow": false,
    "enableCiba": false,
    "enableDpop": false,
    "enableM2m": false,
    "createdAt": "2025-01-10T08:00:00Z",
    "updatedAt": "2025-02-01T15:30:00Z"
  }
}
PUT/api/applications/[id]Requires: manage:applications

Met à jour la configuration d’une application. Tous les champs sont optionnels — seuls les champs fournis sont mis à jour.

Corps de la requête

{
  "name": "Mon Application Web v2",
  "redirectUris": [
    "https://app.votredomaine.com/callback",
    "https://staging.votredomaine.com/callback"
  ],
  "allowedOrigins": [
    "https://app.votredomaine.com",
    "https://staging.votredomaine.com"
  ],
  "enableDeviceFlow": false
}
DELETE/api/applications/[id]Requires: manage:applications

Supprime une application. Cela révoque tous les tokens actifs émis pour l’application. Cette action ne peut pas être annulée.

Réponse de succès

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

Rotation des Secrets

PATCH/api/applications/[id]?action=rotate-secretRequires: manage:applications

Génère un nouveau client secret pour l’application, invalidant immédiatement le précédent. Le nouveau secret est retourné une seule fois. Toutes les intégrations utilisant l’ancien secret doivent être mises à jour.

La rotation du secret invalide immédiatement le précédent. Tous les tokens M2M actifs obtenus avec l’ancien secret continuent de fonctionner jusqu’à leur expiration, mais aucun nouveau token ne peut être obtenu.

Requête : Aucun corps requis.

Réponse de succès

{
  "ok": true,
  "data": {
    "clientId": "cid_abc123",
    "clientSecret": "cs_sk_new...",
    "rotatedAt": "2025-02-18T14:00:00Z"
  }
}

Claims JWT Personnalisés

Les claims personnalisés permettent d’injecter des données supplémentaires dans les access tokens émis par une application spécifique. Les claims sont résolus au moment de l’émission du token et incorporés dans le payload JWT.

Types de Valeur

TypeDescriptionExemple
STATICValeur string fixe"plan": "enterprise"
USER_ATTRIBUTEValeur depuis l’attribut du profil utilisateur"email": user.email
ROLE_BASEDValeur qui change selon les rôles de l’utilisateur"tier": "admin" si rôle admin
EXPRESSIONExpression personnalisée évaluée à l’exécutionuser.roles.includes('admin') ? 'full' : 'read'

Les claims JWT réservés (sub, iss, aud, exp, iat, jti, type, email, roles) ne peuvent pas être écrasés par des claims personnalisés.

GET/api/applications/[id]/custom-claimsRequires: manage:applications

Liste tous les claims personnalisés configurés pour une application.

Réponse de succès

{
  "ok": true,
  "data": [
    {
      "id": "claim_abc",
      "claimKey": "plan",
      "valueType": "STATIC",
      "staticValue": "enterprise",
      "isActive": true
    },
    {
      "id": "claim_def",
      "claimKey": "orgId",
      "valueType": "USER_ATTRIBUTE",
      "userAttribute": "organizationId",
      "isActive": true
    }
  ]
}
POST/api/applications/[id]/custom-claimsRequires: manage:applications

Crée un nouveau claim personnalisé pour une application.

Corps de la requête — Claim statique

{
  "claimKey": "plan",
  "valueType": "STATIC",
  "staticValue": "enterprise"
}

Corps de la requête — Claim attribut utilisateur

{
  "claimKey": "department",
  "valueType": "USER_ATTRIBUTE",
  "userAttribute": "department"
}

Corps de la requête — Claim basé sur le rôle

{
  "claimKey": "accessLevel",
  "valueType": "ROLE_BASED",
  "roleMapping": {
    "admin": "full",
    "editor": "write",
    "viewer": "read"
  }
}

Corps de la requête — Claim expression

{
  "claimKey": "isPremium",
  "valueType": "EXPRESSION",
  "expression": "user.roles.includes('premium') || user.roles.includes('admin')"
}

Codes d’erreur

CodeHTTPDescription
CLAIM_KEY_RESERVED400La clé du claim est un champ JWT réservé
CLAIM_KEY_TAKEN409Un claim avec cette clé existe déjà pour cette application
PATCH/api/applications/[id]/custom-claims/[claimId]Requires: manage:applications

Met à jour un claim personnalisé. Supporte les mises à jour partielles — seuls les champs fournis sont modifiés.

DELETE/api/applications/[id]/custom-claims/[claimId]Requires: manage:applications

Supprime un claim personnalisé. Le claim n’apparaîtra plus dans les tokens émis après la suppression.

POST/api/applications/[id]/custom-claims/previewRequires: manage:applications

Aperçu de comment les claims personnalisés seraient résolus pour un utilisateur spécifique. Utile pour tester la configuration des claims sans émettre un vrai token.

Corps de la requête

{
  "userId": "usr_abc123"
}

Réponse de succès

{
  "ok": true,
  "data": {
    "userId": "usr_abc123",
    "resolvedClaims": {
      "plan": "enterprise",
      "department": "Engineering",
      "accessLevel": "write",
      "isPremium": false
    }
  }
}

Scopes M2M

Les scopes M2M (Machine-to-Machine) définissent ce que peut faire un token client_credentials. Les scopes sont des chaînes libres que ton resource server valide.

GET/api/applications/[id]/m2m-scopesRequires: manage:applications

Liste les scopes M2M configurés pour une application.

Réponse de succès

{
  "ok": true,
  "data": {
    "scopes": ["read:users", "manage:roles"],
    "allowedScopes": ["read:users", "manage:roles", "read:audit-logs"]
  }
}

scopes sont les scopes par défaut émis quand scope n’est pas spécifié dans la requête de token. allowedScopes sont tous les scopes que l’application est autorisée à demander.

POST/api/applications/[id]/m2m-scopesRequires: manage:applications

Configure les scopes M2M pour une application. Remplace complètement la configuration des scopes existante.

Corps de la requête

{
  "scopes": ["read:users"],
  "allowedScopes": ["read:users", "read:audit-logs"]
}

Pages Associées

Architecture