Authentification utilisateurs

01Vue d'ensemble

Chaque espace peut gérer ses propres utilisateurs via les routes réservées /$auth/*. Ces routes permettent l'inscription, la connexion par email/mot de passe ou OAuth (Google, Microsoft), et la gestion de sessions avec des jetons JWT. La clé API (X-API-KEY ou API-KEY) identifie l'espace (l'application) — chaque espace dispose de ses propres utilisateurs et d'une clé de signature JWT indépendante.

ℹ Architecture JWT : La clé de signature JWT est propre à chaque espace et générée automatiquement — deux applications distinctes ne peuvent pas utiliser les jetons l'une de l'autre.

ℹ OAuth par espace : Les identifiants OAuth (Google, Microsoft) se configurent par espace depuis l'interface Mes espaces → OAuth. Chaque espace dispose de ses propres credentials OAuth.

ℹ Ownership : Lorsqu'un utilisateur connecté crée ou met à jour une ressource, son identifiant (owner_id) est automatiquement enregistré. Les requêtes anonymes laissent owner_id à null.

Modes d'authentification :

Mode manuel (par défaut) : le client envoie Authorization: Bearer <access_token> et refresh_token dans le JSON.
Mode cookie (option d'espace AuthCookiesEnabled) : les routes auth lisent/écrivent les tokens en cookies sécurisés.

02Inscription

POST https://api.simpleapi.fr/$auth/register
Content-Type: application/json
X-API-KEY: votre-clé-api

{
  "email": "alice@example.com",
  "password": "MotDePasse123!"
}

Retourne toujours 201 Created avec un message générique. Ensuite, utilisez /$auth/login pour obtenir access_token et refresh_token.

03Connexion

Mode cookie : si AuthCookiesEnabled est actif, cette route pose aussi les cookies simpleapi_at (access) et simpleapi_rt (refresh) en HttpOnly, Secure, SameSite=Lax, Path=/.

POST https://api.simpleapi.fr/$auth/login
Content-Type: application/json
X-API-KEY: votre-clé-api

{
  "email": "alice@example.com",
  "password": "MotDePasse123!"
}

Réponse

JSON

{
  "access_token": "eyJhbGci...",
  "refresh_token": "abc123...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user_id": "019e...",
  "email": "alice@example.com"
}

04Utiliser le jeton d'accès

Ajoutez l'en-tête Authorization: Bearer <access_token> à vos requêtes pour que le serveur associe la ligne créée à votre compte.

POST https://api.simpleapi.fr/commande/abc123
Content-Type: application/json
X-API-KEY: votre-clé-api
Authorization: Bearer eyJhbGci...

{"produit": "livre", "quantite": 2}

05Renouveler le jeton (refresh)

Mode manuel : envoyez refresh_token dans le body JSON (comportement historique).
Mode cookie : le serveur accepte le token depuis le cookie simpleapi_rt et fait aussi la rotation du cookie refresh.

POST https://api.simpleapi.fr/$auth/refresh
Content-Type: application/json
X-API-KEY: votre-clé-api

{"refresh_token": "abc123..."}

06Déconnexion

Mode cookie : la route révoque les tokens puis supprime simpleapi_at et simpleapi_rt côté navigateur.

DELETE https://api.simpleapi.fr/$auth/logout
Content-Type: application/json
X-API-KEY: votre-clé-api

{"refresh_token": "abc123..."}

07Profil utilisateur connecté

En mode manuel, fournissez l'en-tête Authorization. En mode cookie, /$auth/me accepte aussi le cookie simpleapi_at (fallback sur header si présent).

GET https://api.simpleapi.fr/$auth/me
X-API-KEY: votre-clé-api
Authorization: Bearer eyJhbGci...

08Connexion OAuth (Google / Microsoft)

Récupérez l'URL d'autorisation, redirigez l'utilisateur, puis échangez le code contre un jeton.

Si le mode cookie est actif, /$auth/oauth/{provider}/token pose aussi les cookies auth.

ℹ Prérequis : configurez vos credentials OAuth depuis Mes espaces → OAuth avant d'utiliser ces routes.

Étape 1 — Obtenir l’URL d’autorisation

GET https://api.simpleapi.fr/$auth/oauth/google/authorize?redirect_uri=https://monapp.fr/callback
X-API-KEY: votre-clé-api

Étape 2 — Échanger le code OAuth contre un jeton JWT

POST https://api.simpleapi.fr/$auth/oauth/google/token
Content-Type: application/json
X-API-KEY: votre-clé-api

{
  "code": "4/0AfJohX...",
  "state": "xyz...",
  "redirect_uri": "https://monapp.fr/callback"
}

Remplacez google par microsoft pour utiliser le fournisseur correspondant.

09Récapitulatif des routes

Méthode	Route	Description	Auth requise
POST	`/$auth/register`	Inscription	—
POST	`/$auth/login`	Connexion	—
POST	`/$auth/refresh`	Renouveler le jeton	refresh_token (manuel) / cookie refresh (mode cookie)
DELETE	`/$auth/logout`	Déconnexion	refresh_token (manuel) / cookie refresh (mode cookie)
GET	`/$auth/me`	Profil utilisateur	Authorization (manuel) / cookie access (mode cookie)
GET	`/$auth/oauth/{provider}/authorize`	URL d'autorisation OAuth	—
POST	`/$auth/oauth/{provider}/token`	Échange code OAuth → JWT	—

CORS / navigateur (mode cookie) : utilisez credentials: 'include' côté navigateur, gardez un Origin autorisé par l'espace, et préservez Access-Control-Allow-Credentials côté API.

Authentification des utilisateurs