Skip to main content

Authentication

L'API supporte deux modes : cookies de session (pour l'app web) et API keys bearer (pour scripts, CI, integrations).

API keys (recommande pour scripts)​

Creer une API key​

  1. Frontend : Configuration projet -> API keys -> Generer.
  2. Choisir : nom, scopes (read, write, admin), expiration optionnelle.
  3. Auralith affiche une seule fois le secret complet (ak_<prefix>_<secret>). Notez-le, vous ne pourrez plus le voir.

Utiliser une API key​

curl https://app.auralith.io/api/v1/projects \
  -H "Authorization: Bearer ak_abc123_def456789..."

Scopes​

ScopePermet
readGET sur projets / connexions / patches / audit
writePOST / PATCH sur patches, seeds, anonymize. PAS de DELETE.
adminDELETE, modification de policies, gestion API keys

Une API key admin reste limitee aux projets auxquels son owner a acces. Pas d'escalade au-dela du user createur.

Revocation​

curl -X DELETE https://app.auralith.io/api/v1/api-keys/{id} \
  -H "Authorization: Bearer ..."

Revocation immediate. La key revokee porte revoked_at != null et est refusee par l'authentification.

Cookies de session (web app)​

# Login
curl -X POST https://app.auralith.io/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"...","password":"..."}' \
  -c cookies.txt -i

La reponse pose deux cookies : session (httpOnly) et csrf_token. Pour les requetes mutantes, ajouter le header X-CSRF-Token avec la valeur du cookie csrf_token.

CSRF=$(grep csrf_token cookies.txt | awk '{print $7}')
curl -X POST https://app.auralith.io/api/v1/projects \
  -b cookies.txt \
  -H "X-CSRF-Token: $CSRF" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-project"}'

OAuth​

Pour les integrations interactives (utiliser un autre Auralith comme IdP n'est pas supporte ; OAuth ici est pour le login des users via Google / GitHub).

2FA​

Si l'user a 2FA actif, le login en deux etapes :

# Etape 1 : password ok -> 200 avec partial_token
curl -X POST .../auth/login -d '...'
# {"partial_token":"...", "needs_2fa": true}

# Etape 2 : code TOTP
curl -X POST .../auth/login/2fa \
  -d '{"partial_token":"...","code":"123456"}'
# Pose les vrais cookies session + CSRF

Les API keys ne sont pas affectees par 2FA — elles authentifient leur owner sans reverification.

Pieges courants​

  • API key dans Git : ne jamais commit. Utiliser un secret manager CI (GitHub Actions secrets, Vault, etc.).
  • CORS + cookies : si vous appelez l'API depuis un autre domaine, configurer CORS_ORIGINS cote API ET credentials: 'include' cote fetch JS.
  • Expiration API key : verifier expires_at dans la reponse de creation. Au-dela, 401.

Voir aussi​