Authentification

Vue d'ensemble

L'API Oquira Business utilise des Clés API pour les intégrations serveur-à-serveur et des Tokens de Session pour les applications clientes de type tableau de bord. Cette page explique comment utiliser chaque méthode de manière sécurisée.

Clés API

Les clés API sont la méthode recommandée pour authentifier vos serveurs backend. Elles fournissent un accès sécurisé et durable à l'API.

Obtenir vos Clés API

1. Connectez-vous au Tableau de bord Oquira
2. Naviguez vers Paramètres > Clés API
3. Cliquez sur Générer une Nouvelle Clé
4. Sélectionnez les portées (permissions) appropriées
5. Copiez et stockez votre clé de manière sécurisée

Important : Les clés API ne sont affichées qu'une seule fois. Stockez-les immédiatement de manière sécurisée après leur création.

Utiliser les Clés API

Vous devez fournir votre clé API en utilisant l'en-tête X-API-Key :

curl -X GET "https://api.oquira.com/v1/business/services" \
  -H "X-API-Key: votre_cle_api_ici"

Exemple de Requête

curl -X GET "https://api.oquira.com/v1/business/services" \
  -H "X-API-Key: votre_cle_api_ici" \
  -H "Content-Type: application/json"

Portées des Clés API

Lors de la création d'une clé API, vous pouvez limiter ses permissions :

Authentification par Session

Pour les applications côté client (comme les tableaux de bord personnalisés), vous pouvez utiliser l'authentification par session.

Connexion

Authentifiez un utilisateur et recevez une session :

curl -X POST "https://api.oquira.com/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@yourbusiness.com",
    "password": "yourpassword"
  }'

Réponse

{
  "success": true,
  "data": {
    "user": {
      "id": "clsh8b4c5000308l2bh3z6p9k",
      "email": "admin@yourbusiness.com",
      "firstName": "Jane",
      "lastName": "Doe",
      "role": "admin",
      "accountType": "business"
    },
    "session": {
      "token": "sess_clsh8n4p5000708l2bh3z6p9k",
      "expiresAt": "2024-03-22T10:00:00.000Z"
    }
  }
}

Utiliser la Session

Les clients web doivent utiliser le cookie better-auth.session_token pour les requêtes ultérieures. Le cookie est automatiquement défini après une connexion réussie.

Pour l'accès API avec sessions :

curl -X GET "https://api.oquira.com/v1/business/dashboard" \
  -H "Cookie: better-auth.session_token=sess_xyz789..."

Rafraîchir la Session

Les sessions expirent après une période d'inactivité. Pour maintenir la session active :

curl -X POST "https://api.oquira.com/v1/auth/session/refresh" \
  -H "Cookie: better-auth.session_token=sess_xyz789..."

Déconnexion

Terminez une session explicitement :

curl -X POST "https://api.oquira.com/v1/auth/logout" \
  -H "Cookie: better-auth.session_token=sess_xyz789..."

Bonnes Pratiques de Sécurité

Gestion des Clés

• N'exposez jamais les clés API dans le code côté client (navigateurs, applications mobiles)
• Utilisez des variables d'environnement pour stocker les clés dans vos applications
• Rotez les clés régulièrement, surtout après le départ de membres de l'équipe
• Utilisez des clés distinctes pour différents services ou applications

Séparation des Environnements

• Utilisez des clés distinctes pour les environnements de développement et de production pour éviter toute modification accidentelle des données.

Contrôle d'Accès

• Limitez les portées des clés aux permissions strictement nécessaires
• Surveillez l'utilisation de l'API dans votre tableau de bord pour détecter toute activité inhabituelle
• Configurez des alertes pour les tentatives d'authentification échouées

Rotation des Clés

Si vous suspectez qu'une clé a été compromise :

1. Allez dans Paramètres > Clés API dans votre tableau de bord
2. Générez une nouvelle clé avec les mêmes portées
3. Mettez à jour vos applications avec la nouvelle clé
4. Révoquez l'ancienne clé une fois la transition terminée

Réponses d'Erreur

Les erreurs d'authentification retournent des réponses d'erreur standard :

Exemple de Réponse d'Erreur

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Clé API invalide ou expirée",
    "timestamp": "2024-03-20T10:00:00.000Z",
    "requestId": "req_5f2b8c9d1e"
  }
}

Étapes Suivantes

• Mise en route - Effectuez votre premier appel API
• Réponses - Découvrez les formats de réponse
• Erreurs - Gérez les erreurs dans votre intégration
• Limites de taux - Comprenez les limites d'utilisation de l'API