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

# Authentification

> Apprenez à authentifier vos requêtes API

## Authentification par clé API

L'API OneClickDz Flexy utilise l'authentification par clé API. Toutes les requêtes doivent inclure votre clé API dans l'en-tête de la requête.

### Format de l'en-tête

```http theme={null}
X-Access-Token: YOUR_API_KEY
```

<Note>
  Le nom de l'en-tête est `X-Access-Token` (et non `Authorization`). Assurez-vous d'utiliser le bon nom d'en-tête.
</Note>

## Types de clés API

Vous avez accès à deux types de clés API :

<CardGroup cols={2}>
  <Card title="Clé Sandbox" icon="flask">
    **Objectif** : Tests et développement - Aucune déduction de solde réel - Réponses simulées - Numéros de test spéciaux disponibles - Sûre pour le développement
  </Card>

  <Card title="Clé Production" icon="rocket">
    **Objectif** : Transactions en direct - Déduction de solde réel - Intégration opérateur en direct - Prête pour la production - À utiliser avec précaution
  </Card>
</CardGroup>

## Générer des clés API

<Steps>
  <Step title="Connexion au tableau de bord">
    Visitez [enterprise.oneclickdz.com](https://enterprise.oneclickdz.com/api-keys) et connectez-vous à votre compte
  </Step>

  <Step title="Accéder aux paramètres">Allez dans Paramètres → Configuration API</Step>

  <Step title="Générer les clés">
    Cliquez sur « Générer une clé API » pour les environnements Sandbox et Production
  </Step>

  <Step title="Enregistrer de manière sécurisée">
    Copiez et stockez vos clés dans un endroit sécurisé. Vous ne pourrez plus les voir après.
  </Step>
</Steps>

## Valider votre clé API

Testez votre clé API en utilisant l'endpoint de validation :

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.oneclickdz.com/v3/validate \
    --header 'X-Access-Token: YOUR_API_KEY'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.oneclickdz.com/v3/validate", {
    headers: {
      "X-Access-Token": process.env.ONECLICKDZ_API_KEY,
    },
  });

  const data = await response.json();

  if (data.success) {
    console.log("API key is valid!");
    console.log("Account:", data.data.username);
    console.log("Key type:", data.data.apiKey.type);
  } else {
    console.error("API key validation failed:", data.error);
  }
  ```

  ```python Python theme={null}
  import requests
  import os

  response = requests.get(
      'https://api.oneclickdz.com/v3/validate',
      headers={'X-Access-Token': os.getenv('ONECLICKDZ_API_KEY')}
  )

  data = response.json()

  if data['success']:
      print('API key is valid!')
      print(f"Account: {data['data']['username']}")
      print(f"Key type: {data['data']['apiKey']['type']}")
  else:
      print(f"API key validation failed: {data['error']}")
  ```

  ```php PHP theme={null}
  <?php
  $apiKey = getenv('ONECLICKDZ_API_KEY');
  $ch = curl_init("https://api.oneclickdz.com/v3/validate");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Access-Token: " . $apiKey]);
  $response = curl_exec($ch);
  $data = json_decode($response, true);

  if ($data['success']) {
      echo "API key is valid!\n";
      echo "Account: " . $data['data']['username'] . "\n";
      echo "Key type: " . $data['data']['apiKey']['type'] . "\n";
  } else {
      echo "API key validation failed: " . json_encode($data['error']) . "\n";
  }
  ?>
  ```
</CodeGroup>

### Réponse en cas de succès

```json theme={null}
{
  "success": true,
  "data": {
    "username": "+213665983439",
    "apiKey": {
      "key": "ea27b376-9f5c-4b09-883f-1b96cd7b541c",
      "isEnabled": true,
      "type": "SANDBOX",
      "allowedips": [],
      "scope": "READ-WRITE"
    }
  }
}
```

## Propriétés de la clé API

Votre clé API inclut les propriétés suivantes :

| Propriété    | Description                         |
| ------------ | ----------------------------------- |
| `key`        | Votre identifiant de clé API unique |
| `isEnabled`  | Indique si la clé est active        |
| `type`       | `SANDBOX` ou `PRODUCTION`           |
| `allowedips` | Liste blanche d'adresses IP         |
| `scope`      | `READ-WRITE` ou `READ-ONLY`         |

## Liste blanche d'adresses IP

Pour une sécurité renforcée, vous pouvez restreindre vos clés API à des adresses IP spécifiques. Chaque environnement (Production et Sandbox) possède sa propre liste blanche IP indépendante.

<Steps>
  <Step title="Accéder aux paramètres API">
    Accédez à Paramètres → Configuration API dans votre tableau de bord
  </Step>

  <Step title="Ajouter des adresses IP">
    Saisissez les adresses IP spécifiques pour chaque environnement : - **Liste blanche IP Production** : contrôle l'accès pour votre clé API de production - **Liste blanche IP Sandbox** : contrôle l'accès pour votre clé API sandbox - Laissez vide pour autoriser toutes les adresses IP
  </Step>

  <Step title="Enregistrer les modifications">
    Cliquez sur « Mettre à jour la liste blanche IP » pour appliquer les changements
  </Step>
</Steps>

<Warning>
  Lorsque la liste blanche IP contient des adresses, seules ces IP spécifiques seront autorisées. Les requêtes provenant d'autres IP seront rejetées avec une erreur 403.
</Warning>

### Format de la liste blanche IP

Ajoutez des adresses IP spécifiques à la liste blanche, une par ligne :

* `203.0.113.45` - Autorise uniquement cette adresse IP
* `198.51.100.23` - Une autre adresse IP spécifique

<Tip>
  Laissez la liste blanche vide pour autoriser toutes les adresses IP (comportement par défaut). Ajoutez des IP pour activer les restrictions.
</Tip>

## Portées des clés

Les clés API peuvent avoir différents niveaux d'accès :

### READ-WRITE (par défaut)

Accès complet à toutes les opérations :

* Consulter le solde et les transactions
* Envoyer des recharges
* Passer des commandes
* Vérifier les statuts

### READ-ONLY

Limité aux opérations de lecture :

* Consulter le solde et les transactions
* Vérifier le statut des recharges
* Lister les commandes
* Impossible de créer de nouvelles transactions

<Tip>
  Utilisez les clés READ-ONLY pour les tableaux de bord de reporting ou les outils d'analyse qui ne doivent pas modifier les données.
</Tip>

## Réponses d'erreur

### 400 - Clé API manquante

```json theme={null}
{
  "success": false,
  "error": {
    "code": "MISSING_ACCESS_TOKEN",
    "message": "Access token is required"
  },
  "requestId": "req_abc123"
}
```

### 401 - Clé API invalide

```json theme={null}
{
  "success": false,
  "error": {
    "code": "INVALID_ACCESS_TOKEN",
    "message": "The provided access token is invalid",
    "details": {
      "attemptsLeft": 3
    }
  },
  "requestId": "req_abc123"
}
```

<Warning>
  Après 5 tentatives d'authentification échouées, votre IP sera temporairement bloquée pendant 15 minutes.
</Warning>

### 403 - IP non autorisée

```json theme={null}
{
  "success": false,
  "error": {
    "code": "IP_NOT_ALLOWED",
    "message": "Your IP address 203.0.113.45 is not whitelisted for this PRODUCTION API key. Add your IP to the whitelist at  https://app.oneclickdz.com/#/settings"
  },
  "requestId": "req_abc123"
}
```

<Tip>
  La réponse d'erreur inclut votre adresse IP actuelle et l'environnement (SANDBOX ou PRODUCTION) pour vous aider à identifier rapidement quelle liste blanche doit être mise à jour.
</Tip>

### 403 - IP Bloquée

```json theme={null}
{
  "success": false,
  "error": {
    "code": "IP_BLOCKED",
    "message": "Your IP has been temporarily blocked due to too many invalid attempts"
  },
  "requestId": "req_abc123"
}
```

## Bonnes pratiques de sécurité

<AccordionGroup>
  <Accordion title="Stocker les clés en sécurité" icon="lock">
    * Ne jamais committer les clés API dans le contrôle de version
    * Utiliser des variables d'environnement ou des systèmes de gestion des secrets
    * Renouveler les clés périodiquement
    * Utiliser des clés différentes pour différents environnements
  </Accordion>

  <Accordion title="Utiliser uniquement HTTPS" icon="shield-halved">
    * Toujours utiliser les endpoints HTTPS
    * Ne jamais envoyer les clés API via HTTP
    * Vérifier les certificats SSL
  </Accordion>

  <Accordion title="Mettre en place la liste blanche d'IP" icon="list-check">
    * N'autoriser que les adresses IP nécessaires
    * Utiliser des IP spécifiques plutôt que des plages larges
    * Mettre à jour la liste blanche lors des changements d'infrastructure
  </Accordion>

  <Accordion title="Surveiller l'utilisation de l'API" icon="chart-line">
    * Suivre régulièrement l'utilisation des clés API
    * Configurer des alertes pour les activités inhabituelles
    * Consulter les journaux d'accès
    * Révoquer immédiatement les clés compromises
  </Accordion>

  <Accordion title="Limiter la portée des clés" icon="eye-slash">
    * Utiliser des clés READ-ONLY lorsque possible
    * Créer des clés séparées pour différents services
    * Appliquer le principe du moindre privilège
  </Accordion>
</AccordionGroup>

## Rotation des clés

Il est recommandé de renouveler vos clés API périodiquement :

<Steps>
  <Step title="Générer une nouvelle clé">Créez une nouvelle clé API depuis votre tableau de bord</Step>

  <Step title="Mettre à jour l'application">
    Déployez votre application avec la nouvelle clé
  </Step>

  <Step title="Vérifier">Testez que la nouvelle clé fonctionne correctement</Step>

  <Step title="Révoquer l'ancienne clé">
    Une fois vérifiée, révoquez l'ancienne clé depuis votre tableau de bord
  </Step>
</Steps>

<Tip>Renouvelez les clés au moins tous les 90 jours pour une sécurité renforcée.</Tip>

## Besoin d'aide ?

Si vous rencontrez des problèmes d'authentification :

1. Vérifiez que votre clé API est correcte
2. Vérifiez que vous utilisez le bon nom d'en-tête (`X-Access-Token`)
3. Assurez-vous que votre IP est dans la liste blanche (si activée)
4. Vérifiez l'état de l'API sur [status.oneclickdz.com](https://status.oneclickdz.com)
5. Contactez le support à [support@oneclickdz.com](mailto:support@oneclickdz.com)