Authentification

Authentification

L'API ZenFlip prend en charge deux méthodes d'authentification : la connexion par email/mot de passe (jetons JWT) et Google OAuth. Les clés API pour la communication serveur à serveur sont bientôt disponibles. Tous les endpoints protégés nécessitent un jeton Bearer valide dans l'en-tête Authorization.

Connexion par email et mot de passe

Inscription

Créez un nouveau compte et une organisation :

`bash curl -X POST https://api.zenflip.io/v1/auth/signup \ -H "Content-Type: application/json" \ -d '{ "email": "developer@example.com", "password": "SecureP@ssw0rd!", "name": "Alex Chen", "organizationName": "Acme Publishing" }' `

Après l'inscription, un email de vérification est envoyé. Le compte doit être vérifié avant d'obtenir un accès complet.

Connexion

Échangez vos identifiants contre des jetons JWT :

`bash curl -X POST https://api.zenflip.io/v1/auth/login \ -H "Content-Type: application/json" \ -d '{ "email": "developer@example.com", "password": "SecureP@ssw0rd!" }' `

Réponse :

`json { "accessToken": "eyJhbGciOiJIUzI1NiIs...", "refreshToken": "eyJhbGciOiJIUzI1NiIs...", "expiresIn": 3600, "user": { "id": "550e8400-e29b-41d4-a716-446655440000", "email": "developer@example.com", "name": "Alex Chen", "role": "owner", "emailVerified": true }, "organization": { "id": "660e8400-e29b-41d4-a716-446655440000", "name": "Acme Publishing", "plan": "creator" } } `

Le accessToken expire après le nombre de secondes indiqué par expiresIn (par défaut : 3600 secondes / 1 heure). Le refreshToken a une durée de vie plus longue et sert à obtenir de nouveaux jetons d'accès sans ressaisir les identifiants.

Utilisation des jetons

Incluez le jeton d'accès dans l'en-tête Authorization pour toutes les requêtes protégées :

`bash curl https://api.zenflip.io/v1/publications \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." `

Avec JavaScript fetch :

`javascript const response = await fetch("https://api.zenflip.io/v1/publications", { headers: { "Authorization": Bearer ${accessToken}, "Content-Type": "application/json" } }); const { data, meta } = await response.json(); `

Rafraîchissement du jeton

Lorsque le jeton d'accès expire, utilisez le jeton de rafraîchissement pour obtenir une nouvelle paire sans demander à l'utilisateur de se reconnecter :

`bash curl -X POST https://api.zenflip.io/v1/auth/refresh \ -H "Content-Type: application/json" \ -d '{ "refreshToken": "eyJhbGciOiJIUzI1NiIs..." }' `

Réponse :

`json { "accessToken": "eyJhbGciOiJIUzI1NiIs...", "refreshToken": "eyJhbGciOiJIUzI1NiIs...", "expiresIn": 3600 } `

Le jeton d'accès et le jeton de rafraîchissement sont renouvelés à chaque appel de rafraîchissement. Stockez le nouveau jeton de rafraîchissement et supprimez l'ancien. Si vous utilisez le tableau de bord web ZenFlip, les jetons sont également définis automatiquement comme cookies httpOnly.

Exemple de rafraîchissement en JavaScript

`javascript async function refreshAccessToken(currentRefreshToken) { const response = await fetch("https://api.zenflip.io/v1/auth/refresh", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ refreshToken: currentRefreshToken }) });

if (!response.ok) { throw new Error("Token refresh failed, user must re-authenticate"); }

const tokens = await response.json(); // Stockez tokens.accessToken et tokens.refreshToken de manière sécurisée return tokens; } `

Google OAuth

ZenFlip prend en charge Google OAuth pour l'authentification unique. Ce flux est basé sur le navigateur et utilise des redirections côté serveur.

Flux

1. Redirigez l'utilisateur vers https://api.zenflip.io/v1/auth/google.

2. L'utilisateur s'authentifie auprès de Google et donne son consentement.

3. Google redirige vers https://api.zenflip.io/v1/auth/google/callback.

4. L'API définit des cookies d'authentification httpOnly et redirige l'utilisateur vers l'URL de callback de votre frontend (ex. : https://app.zenflip.io/auth/google/callback?isNew=0).

Le paramètre isNew indique si un nouveau compte a été créé (1) ou si l'utilisateur s'est connecté à un compte existant (0). Votre frontend lit ce drapeau pour décider s'il faut afficher l'intégration initiale.

Exemple d'intégration

`html <a href="https://api.zenflip.io/v1/auth/google" class="btn-google"> Se connecter avec Google </a> `

Après le callback OAuth, le navigateur de l'utilisateur possède des cookies d'authentification. Les appels API suivants depuis le navigateur seront authentifiés via ces cookies.

Clés API (serveur à serveur) — Bientôt disponible {#api-keys}

Pour les intégrations backend, les webhooks ou les pipelines CI/CD, les clés API fourniront un chemin d'authentification plus simple qui ne nécessite pas le flux de connexion/rafraîchissement. En attendant, utilisez les jetons JWT pour tous les accès API.

Vérification d'email

Les nouveaux comptes nécessitent une vérification d'email. L'API fournit des endpoints pour vérifier et renvoyer l'email de vérification :

`bash

Vérifier avec un jeton provenant du lien email

curl -X POST https://api.zenflip.io/v1/auth/verify-email \ -H "Content-Type: application/json" \ -d '{ "token": "verification-token-from-email" }'

Renvoyer l'email de vérification

curl -X POST https://api.zenflip.io/v1/auth/resend-verification \ -H "Content-Type: application/json" \ -d '{ "email": "developer@example.com" }' `

Réinitialisation du mot de passe

Si un utilisateur oublie son mot de passe, initiez un flux de réinitialisation :

`bash

Demander un email de réinitialisation du mot de passe

curl -X POST https://api.zenflip.io/v1/auth/forgot-password \ -H "Content-Type: application/json" \ -d '{ "email": "developer@example.com" }'

Réinitialiser le mot de passe avec le jeton provenant de l'email

curl -X POST https://api.zenflip.io/v1/auth/reset-password \ -H "Content-Type: application/json" \ -d '{ "token": "reset-token-from-email", "password": "NewSecureP@ssw0rd!" }' `

Profil de l'utilisateur actuel

Récupérez le profil de l'utilisateur authentifié :

`bash curl https://api.zenflip.io/v1/auth/me \ -H "Authorization: Bearer YOUR_TOKEN" `

Déconnexion

Invalidez la session en cours et effacez les cookies :

`bash curl -X POST https://api.zenflip.io/v1/auth/logout \ -H "Authorization: Bearer YOUR_TOKEN" `

Limites de débit

Les endpoints d'authentification ont leurs propres limites de débit pour prévenir les abus :