Référence API

L’API Auris est une API REST qui fournit un accès programmatique à toutes les fonctionnalités IAM : authentification, gestion des utilisateurs, rôles, permissions, organisations, autorisation fine-grained et plus. Toutes les réponses API utilisent JSON.

URL de Base

https://api.altovar.net/api

Remplace api.altovar.net par le domaine où ton Auris est déployé. Si tu utilises le service cloud Auris, ton domaine est celui affiché dans la Console sous Paramètres → Domaines Personnalisés.

Authentification

Bearer Token

La plupart des endpoints nécessitent un access token valide dans le header Authorization :

Authorization: Bearer <access_token>

Les access tokens sont des JWT à courte durée de vie (défaut 15 minutes) obtenus via les endpoints d’authentification. Ils sont signés avec RS256 (ou HS256 selon la configuration) et peuvent être vérifiés localement en utilisant l’endpoint JWKS.

Niveau d’Accès par Type d’Endpoint

Header Tenant

Auris est une plateforme multi-tenant. Les requêtes aux endpoints admin doivent inclure l’identifiant du tenant :

x-tenant: <tenant-id>

Le tenant ID est le nom du realm configuré dans ton déploiement Auris. Pour l’installation par défaut, c’est default. Pour les configurations tenant personnalisées, c’est le nom du realm affiché dans la Console sous Paramètres → Général.

Si le header est omis sur les endpoints qui le nécessitent, l’API retourne 400 Bad Request avec le code MISSING_TENANT.

Format des Requêtes

Utilise Content-Type: application/json pour toutes les requêtes POST, PUT et PATCH avec un corps de requête :

Content-Type: application/json

Exemple de requête :

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

Pour l’upload de fichiers (import utilisateurs), utilise multipart/form-data.

Format des Réponses

Toutes les réponses API suivent un format envelope cohérent.

Réponse de Succès

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

Le champ data contient le résultat. Sa forme varie selon les endpoints et est documentée individuellement pour chaque endpoint.

Réponse d’Erreur

{
  "ok": false,
  "error": {
    "code": "CODE_ERREUR",
    "message": "Description lisible de ce qui s'est mal passé."
  }
}

Codes de Statut HTTP

Codes d’Erreur Courants

Pagination

Les endpoints de liste retournent des résultats paginés en utilisant des numéros de page.

Structure de la Réponse

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

Paramètres de Query

Exemple :

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

Rate Limiting

Chaque réponse inclut des headers de rate limiting :

Quand un rate limit est dépassé, l’API retourne 429 Too Many Requests avec un header Retry-After indiquant combien de secondes attendre avant de réessayer.

Niveaux de Rate Limiting

CORS

Le Cross-Origin Resource Sharing (CORS) est appliqué sur tous les endpoints API. Les origines autorisées doivent être enregistrées dans les paramètres de l’Application dans la Console Auris sous Applications → [App] → Origines Autorisées.

Les requêtes preflight OPTIONS sont gérées automatiquement. Les credentials (cookies) sont autorisés quand l’origine de la requête est enregistrée.

Pour enregistrer une origine :

1. Aller dans Console → Applications
2. Sélectionner ton application
3. Ajouter l’origine dans les Origines Autorisées (ex. https://app.votredomaine.com)

Discovery OIDC

Auris expose un document de discovery OpenID Connect standard :

GET /.well-known/openid-configuration

Cela retourne un document JSON contenant tous les URLs des endpoints, les grant types supportés, les scopes, les algorithmes de signature et autres métadonnées. Les bibliothèques OIDC standard utilisent ceci pour s’auto-configurer.

Exemple de champs de réponse :

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

JWKS

Les clés de signature publiques utilisées pour la vérification JWT sont disponibles sur :

GET /.well-known/jwks.json

Réponse :

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

Les clés sont mises en cache par les clients pendant un maximum d’1 heure (Cache-Control: public, max-age=3600). La rotation des clés ajoute une nouvelle clé au set ; les anciennes clés restent présentes jusqu’à l’expiration des tokens émis.

SDK Client

Plutôt qu’appeler directement l’API, envisage d’utiliser un SDK Auris qui gère automatiquement la gestion des tokens, PKCE, le refresh et la gestion des erreurs :

Consulte la documentation des SDKs pour les guides d’installation et d’utilisation.