Authentification

Toutes les requêtes API nécessitent un token Bearer dans le header Authorization. Les tokens sont émis via l'endpoint de connexion et expirent après 1 an.

Authorization: Bearer {token}

Connexion

POST /auth/login

Authentifie un utilisateur avec son e-mail et son mot de passe. Renvoie un token Bearer pour les appels API suivants.

curl -X POST https://services.gitscrum.com/auth/login \
  -H "Content-Type: application/json" \
  -H "X-Client-Type: api" \
  -d '{
    "email": "jane@acme.co",
    "password": "your-password"
  }'

Corps de la requête

Headers

Réponse 200 OK

{
  "data": {
    "companies": [
      {
        "slug": "acme-corp",
        "name": "Acme Corp",
        "logo": "https://cdn.gitscrum.com/logo.png"
      }
    ],
    "user": {
      "id": 1,
      "uuid": "user-uuid-123",
      "name": "Jane Smith",
      "username": "janesmith",
      "email": "jane@acme.co",
      "avatar": "https://avatar.url/jane.jpg",
      "headline": "Lead Developer",
      "timezone_name": "Europe/Lisbon",
      "language": "en"
    },
    "token_type": "Bearer",
    "access_token": "eyJ0eXAiOiJKV1Q..."
  }
}

Réponses d'erreur

MFA (authentification à deux facteurs)

Si le MFA est activé sur le compte, l'endpoint de connexion renvoie un challenge au lieu d'un token.

Étape 1 — La connexion renvoie un challenge MFA

{
  "mfa_required": true,
  "mfa_token": "random-64-character-string",
  "message": "MFA verification required"
}

Le mfa_token est valide pendant 5 minutes.

Étape 2 — Vérifier le code MFA

POST /auth/login/mfa-verify

curl -X POST https://services.gitscrum.com/auth/login/mfa-verify \
  -H "Content-Type: application/json" \
  -d '{
    "mfa_token": "random-64-character-string",
    "mfa_code": "123456"
  }'

Renvoie la même réponse 200 OK qu'une connexion standard avec access_token.

Raccourci — Vous pouvez également passer mfa_code directement dans le corps de la requête initiale /auth/login pour sauter le flux en deux étapes, si vous disposez déjà du code TOTP.

Vérifier l'authentification

POST /auth/me

Renvoie le profil de l'utilisateur authentifié. Utilisez cet endpoint pour valider un token.

curl -X POST https://services.gitscrum.com/auth/me \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

Réponse 200 OK

{
  "data": {
    "id": 1,
    "uuid": "user-uuid-123",
    "name": "Jane Smith",
    "username": "janesmith",
    "email": "jane@acme.co",
    "avatar": "https://avatar.url/jane.jpg",
    "headline": "Lead Developer",
    "timezone_name": "Europe/Lisbon",
    "language": "en"
  }
}

Actualiser le token

POST /auth/refresh

Révoque le token actuel et en émet un nouveau. Utilisez cet endpoint pour la rotation des tokens sans nécessiter une nouvelle connexion de l'utilisateur.

curl -X POST https://services.gitscrum.com/auth/refresh \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

Réponse 200 OK

{
  "data": {
    "token_type": "Bearer",
    "access_token": "eyJ0eXAiOiJKV1Q..."
  }
}

Après l'actualisation, le token précédent est immédiatement révoqué. Mettez à jour votre token stocké avec le nouvel access_token.

Déconnexion

POST /auth/logout

Révoque le token actuel. Le token ne peut plus être utilisé après cet appel.

curl -X POST https://services.gitscrum.com/auth/logout \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

Réponse 200 OK

{
  "message": "Successful logout"
}

Réponse d'erreur

Si le token est manquant, invalide ou expiré, l'API renvoie 401 Unauthorized :

{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

Référence du token

Bonnes pratiques de sécurité

• N'exposez jamais les tokens dans le code côté client ou les dépôts publics
• Utilisez des variables d'environnement pour stocker les tokens dans vos applications
• Renouvelez les tokens régulièrement via l'endpoint /auth/refresh
• Utilisez HTTPS uniquement — l'API rejette les requêtes en HTTP non chiffré
• Gérez le MFA — vérifiez toujours la présence de mfa_required: true dans les réponses de connexion