5 Méthodes Simples pour Contrôler l'Accès à la Documentation API dans Apidog

Après avoir rédigé la documentation de votre API et être prêt à la publier, une question clé se pose : Qui devrait pouvoir la consulter ?

La documentation doit-elle être entièrement publique ? Ou restreinte à votre équipe interne ? Peut-être que vos partenaires externes ont besoin d'y accéder – mais pas n'importe qui.

Créer une version distincte de la documentation pour chaque scénario serait chronophage et inefficace. En réalité, les besoins d'accès sont souvent très spécifiques – peut-être qu'un seul département devrait la voir, ou que vos partenaires ne devraient y accéder que depuis leur réseau d'entreprise.

Heureusement, Apidog offre plusieurs options de contrôle d'accès pour répondre à tous ces besoins. Lors de la publication d'un site de documentation, sélectionnez simplement la méthode de contrôle d'accès qui correspond à votre cas d'utilisation.

1. Public : Tout le monde peut consulter

Si votre API est ouverte à l'utilisation publique – comme l'API ouverte de votre produit – définissez simplement le contrôle d'accès sur "Public". Toute personne disposant du lien peut consulter la documentation.

Conseil de pro : Apidog propose également un API Hub, une plateforme de type marketplace où les développeurs peuvent parcourir et découvrir des API. Publiez-y votre documentation pour augmenter sa visibilité et son adoption.

2. Protégé par mot de passe : Barrière simple

Parfois, vous ne voulez pas que votre documentation soit entièrement publique, mais vous souhaitez également éviter une configuration complexe. La protection par mot de passe est une solution simple : définissez un mot de passe, et seules les personnes qui le connaissent peuvent accéder à la documentation.

La configuration est facile :

• Choisissez « Protégé par mot de passe »
• Définissez un mot de passe manuellement ou laissez le système en générer un
• Partagez-le avec vos collègues ou partenaires

Idéal pour : Le partage à court terme ou temporaire, comme permettre à un partenaire de réviser la conception de votre API. Ensuite, il suffit de mettre à jour le mot de passe ou de dépublier la documentation. Simple et propre.

Mais gardez à l'esprit : Les mots de passe peuvent être partagés involontairement. Si vous avez besoin d'un contrôle plus strict, envisagez d'autres options.

3. Liste blanche d'IP : Restreindre l'accès à des réseaux spécifiques

Si votre équipe ou vos partenaires sont basés dans des bureaux fixes, la liste blanche d'IP peut être votre meilleur choix.

Cela fonctionne comme suit :

• Seuls les utilisateurs provenant des adresses IP ou des plages spécifiées peuvent accéder à la documentation
• Les IP non autorisées sont automatiquement refusées

Considérez-le comme un pare-feu pour votre documentation.

Idéal pour :

• Environnements d'entreprise
• Limiter l'accès à votre réseau interne
• Permettre l'accès aux partenaires uniquement depuis leur réseau de bureau

Vous pouvez configurer une seule IP ou une plage d'IP entière.

Bonus : Vous pouvez également activer la liste blanche d'IP pour l'accès aux projets d'équipe dans les Paramètres d'équipe d'Apidog (plan Entreprise requis). Une fois activé, seuls les utilisateurs provenant des IP autorisées peuvent accéder à vos projets internes.

4. Liste blanche d'e-mails : Accès basé sur l'identité

Craignez-vous que les mots de passe ne soient divulgués ou que les adresses IP ne changent souvent ? La liste blanche d'e-mails est une alternative flexible et sécurisée.

Ajoutez simplement les adresses e-mail de votre équipe ou de vos partenaires à la liste blanche. Les utilisateurs peuvent ensuite accéder à la documentation via un code de vérification unique envoyé par e-mail.

Il prend également en charge les caractères génériques – par exemple, *@apidog.com permet à tous les utilisateurs du domaine de votre entreprise d'accéder à la documentation.

Avantages :

• Facile à gérer : ajoutez ou supprimez des utilisateurs selon les besoins
• Plus sûr que les mots de passe : les utilisateurs non autorisés ne peuvent pas consulter la documentation même s'ils ont le lien
• Idéal pour les équipes distribuées ou les effectifs mobiles

5. Page de connexion personnalisée : Intégration avec votre propre système d'authentification

Si aucune des méthodes ci-dessus ne répond à vos besoins, il existe une option plus avancée : la Page de connexion personnalisée. Cela vous permet de connecter votre propre système d'authentification pour contrôler l'accès.

Voici comment cela fonctionne :

• Lorsqu'un utilisateur tente d'accéder au site de documentation, il est redirigé vers votre page de connexion.
• Après l'authentification, votre serveur génère un jeton JWT.
• L'utilisateur est redirigé vers le site de documentation avec le jeton comme paramètre.
• Apidog vérifie le jeton et accorde l'accès s'il est valide.

Cette approche vous permet de définir les permissions exactement selon les besoins de votre entreprise. Bien que cela nécessite un certain développement, c'est une excellente solution pour les entreprises ayant des besoins complexes en matière de contrôle d'accès.

Consultez les Docs d'aide pour plus de détails sur l'implémentation d'une page de connexion personnalisée.

Comment choisir la bonne méthode de contrôle d'accès

Avec tant d'options, vous pourriez vous demander : Laquelle devrais-je choisir ?

Cela dépend de votre cas d'utilisation :

Astuce : Vous pouvez combiner plusieurs méthodes. Par exemple :

• Utilisez une liste blanche d'IP pour les membres de l'équipe interne
• Utilisez une liste blanche d'e-mails pour les partenaires externes
• Utilisez la protection par mot de passe pour les démonstrations temporaires

Avec Apidog, vous pouvez publier plusieurs sites de documentation, chacun avec son propre contrôle d'accès et un ensemble d'endpoints API adapté. Cela signifie que les différentes audiences ne voient que ce dont elles ont besoin – ni plus, ni moins.