> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.gimpayapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Apprenez à authentifier vos requêtes vers l'API GIMgar Sud.

Toutes les requêtes vers l'API GIMgar Sud, à l'exception de la génération du token elle-même, doivent être authentifiées. Ce guide explique le flux d'authentification et comment l'implémenter en toute sécurité.

## Vue d'ensemble

GIMgar Sud utilise le protocole **OAuth 2.0** avec le flux `client_credentials` : vous échangez un `client_id` et un `client_secret` contre un **token Bearer** (JWT), que vous incluez ensuite dans l'en-tête `Authorization` de chaque appel.

<Steps>
  <Step title="Récupérez vos identifiants">
    Votre `client_id` et votre `client_secret` vous sont fournis par GIM-UEMOA lors de votre intégration à la plateforme.
  </Step>

  <Step title="Générez un token">
    Appelez `POST {{baseUrl}}/api/v1/auth/token` avec vos identifiants pour obtenir un `access_token`.
  </Step>

  <Step title="Utilisez le token">
    Incluez `Authorization: Bearer {{access_token}}` dans l'en-tête de chaque requête vers les autres endpoints.
  </Step>

  <Step title="Renouvelez avant expiration">
    Le token expire après `expires_in` secondes. Générez-en un nouveau proactivement avant qu'il n'expire plutôt que d'attendre une erreur `401`.
  </Step>
</Steps>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url {{baseUrl}}/api/v1/auth/token \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data grant_type=client_credentials \
    --data client_id={{client_id}} \
    --data client_secret={{client_secret}}
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("{{baseUrl}}/api/v1/auth/token", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "client_credentials",
      client_id: "{{client_id}}",
      client_secret: "{{client_secret}}",
    }),
  });

  const { access_token } = await response.json();
  ```
</CodeGroup>

La réponse contient votre `access_token`, sa durée de validité (`expires_in`, en secondes) et son type (`token_type`, toujours `Bearer`).

## Utiliser le token

Incluez le token dans l'en-tête `Authorization` de chaque requête vers une API protégée :

```http theme={null}
Authorization: Bearer {{access_token}}
```

## Sécurité des identifiants

<Steps>
  <Step title="Gardez vos identifiants privés">
    Ne partagez jamais votre `client_secret` dans du code accessible publiquement (dépôt Git, code côté client, réseaux sociaux).
  </Step>

  <Step title="Appelez le token endpoint depuis un backend">
    Le `client_secret` ne doit jamais être exposé côté navigateur ou dans une application mobile — générez le token depuis un serveur que vous contrôlez.
  </Step>

  <Step title="Utilisez des variables d'environnement">
    Stockez `client_id` et `client_secret` dans des variables d'environnement ou un gestionnaire de secrets, jamais en dur dans le code.
  </Step>

  <Step title="Limitez l'accès">
    Seules les personnes qui en ont réellement besoin doivent avoir accès à ces identifiants.
  </Step>

  <Step title="Utilisez HTTPS">
    Toutes les requêtes doivent transiter en HTTPS pour éviter toute interception du token en transit.
  </Step>
</Steps>

## Réponses d'erreur

| Code http | Cause possible                                                         |
| --------- | ---------------------------------------------------------------------- |
| `400`     | `grant_type`, `client_id` ou `client_secret` manquant ou invalide.     |
| `401`     | Token manquant, invalide ou expiré sur un appel vers une API protégée. |
| `500`     | Problème serveur lors de la génération du token.                       |

## Étapes suivantes

<CardGroup cols={2}>
  <Card title="Référence API" icon="code" href="/api-reference/introduction">
    Explorez l'ensemble des endpoints disponibles.
  </Card>

  <Card title="Erreurs" icon="triangle-exclamation" href="/getting-started/errors">
    Comprenez les codes d'erreur retournés par l'API.
  </Card>

  <Card title="Tester votre intégration" icon="flask" href="/getting-started/testing">
    Utilisez le sandbox interactif pour exécuter vos premiers appels.
  </Card>
</CardGroup>


## OpenAPI

````yaml openapi.json POST /api/v1/auth/token
openapi: 3.0.1
info:
  title: Registre des APIs (GIM Gar Sud)
  version: 1.0.7
servers:
  - url: https://egimgarsud.gimpayapp.com
    description: Serveur de production
security: []
tags:
  - name: Favorite beneficiaries and mini marketplaces
    description: >-
      Une mini market place est une plateforme de vente de produits et de
      services locaux. On les utilise dans les APIs ...
paths:
  /api/v1/auth/token:
    post:
      tags:
        - Authentification
      summary: S'authentifier et obtenir un token
      description: >-
        Permet à un utilisateur de s'authentifier en fournissant ses
        identifiants et de recevoir un token JWT à utiliser pour les
        consommations d'API.
      operationId: genererToken
      requestBody:
        description: Identifiants de connexion de l'utilisateur.
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AuthRequest'
        required: true
      responses:
        '200':
          description: Authentification réussie. Le token est retourné dans la réponse.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '400':
          description: 'Requête invalide (ex : champ manquant).'
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '500':
          description: Une erreur inattendue s'est produite, veuillez réessayer.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AuthResponse'
components:
  schemas:
    AuthRequest:
      required:
        - client_id
        - client_secret
        - grant_type
      type: object
      properties:
        grant_type:
          type: string
          description: Le type d'authentification
          example: client_credentials
        client_id:
          type: string
          description: L'identifiant du client
        client_secret:
          type: string
          description: Le secret du client
    AuthResponse:
      type: object
      properties:
        access_token:
          type: string
          description: >-
            Token JWT signé (au format Bearer) à inclure dans l'en-tête
            Authorization des requêtes vers les APIs protégées.
        expires_in:
          type: integer
          format: int32
          description: Durée de validité du token, en secondes.
        token_type:
          type: string
          description: Type du token. Toujours Bearer.
        refresh_expires_in:
          type: integer
          format: int32
          description: Durée de vie du token de rafraîchissement. Toujours 0.
        scope:
          type: string
          description: Liste des portées accordées au token.
        not_before_policy:
          type: integer
          format: int32
          description: >-
            Timestamp Unix indiquant que le token ne doit pas être accepté avant
            ce moment.

````