Création d’une clé API

Les appels API Megaport nécessitent un jeton d’accès que vous pouvez générer après avoir créé une clé API. Un jeton d’accès est requis pour authentifier les utilisateurs de l’API et fournit un accès temporaire aux parties nécessaires du Megaport Portal uniquement.

Il est recommandé de créer un compte administrateur d’entreprise machine à machine (M2M) pour accéder à l’API Megaport et créer des clés API. Dans le cas où un utilisateur humain est désactivé ou verrouillé sur son compte, les clés API créées par cet utilisateur seront également suspendues, ce qui pourrait empêcher toute intégration API de fonctionner.

Les clés API ne sont valables que dans l’environnement dans lequel elles ont été générées. Si vous avez besoin de clés API pour accéder à un environnement différent, connectez-vous au Megaport Portal de cet environnement pour y générer les clés API.

Remarque

Vous devez être connecté au Megaport Portal en tant qu’utilisateur doté du rôle Company Admin (Administrateur de l’entreprise) pour créer une clé API. Pour plus d’informations, voir Gestion des rôles d’utilisateur.
Un maximum de cinq clés API peut être créé par entreprise.

Cette rubrique décrit les tâches suivantes :

Pour créer une clé API dans le Megaport Portal
Pour générer un jeton d’accès dans Postman

Pour créer une clé API dans le Megaport Portal

Dans le Megaport Portal, sélectionnez Tools (Outils) > API Key Generator (Générateur de clés API).
La page API Keys (Clés API) vous permet de créer des clés API, mais également de visualiser et de modifier les clés API existantes.
Spécifiez les détails de la clé API.
- Name (Nom) – Saisissez un nom pour la clé API.
  Il doit s’agir d’un nom descriptif permettant d’identifier l’objet de la clé.
  Remarque
  - Trois caractères minimum sont requis pour le nom de la clé API.
  - Aucun caractère spécial n’est autorisé, à l’exception du tiret et du trait d’union.
- Role (Rôle) – Sélectionnez le rôle de l’utilisateur qui utilisera l’API.
  Les options suivantes sont disponibles :
  - Company Admin (Administrateur de l’entreprise)
  - Read Only (Lecture seule)
- Token Expiry (Minutes) (Expiration du jeton (minutes)) – Saisissez le délai (en minutes) après lequel le jeton généré par cette clé expirera. La valeur minimum est de 5 minutes et la valeur maximum de 24 heures (1440 minutes). Après l’expiration du jeton, vous devrez générer un nouveau jeton d’accès.
Cliquez sur Generate Key (Générer une clé).
La clé API est créée et l’invite Your API Key (Votre clé API) apparaît.

Important

Copiez votre nouvelle clé API et votre secret de clé API, et stockez ces identifiants à un emplacement sûr. Vous devrez les utiliser pour générer des jetons d’accès. Assurez-vous de copier le secret de la clé API, car il ne sera plus affiché après la fermeture de cette invite.
Cliquez sur Copy (Copier) à droite du champ API Key (Clé API) et collez la clé (ID client) à un emplacement sûr.
Cliquez sur Copy (Copier) à droite du champ API Key Secret (Secret de clé API) et collez le secret client à un emplacement sûr.
Cliquez sur Close (Fermer).
La clé API est créée et s’affiche dans la zone Active API Keys (Clés API actives) de l’écran.
Dans la zone Active API Keys (Clés API actives), vous pouvez modifier le nom de la clé, la supprimer et afficher l’historique des modifications apportées à la clé.

Génération d’un jeton d’accès

Après avoir créé la clé API, composée d’un ID client et d’un secret client, vous pouvez générer un jeton d’accès pour authentifier les utilisateurs de l’API. Ces instructions décrivent comment effectuer cette opération en utilisant Postman et la collection Megaport. Pour obtenir des informations sur la configuration de Postman, voir API Megaport.

L’URL de demande que vous devez utiliser dépend de l’environnement dans lequel vous générez le jeton d’accès. Dans chaque environnement, les URL de demande suivantes doivent être utilisées :

Environnement de production : - https://auth-m2m.megaport.com/oauth2/token
Environnement de test : - https://oauth-m2m-staging.auth.ap-southeast-2.amazoncognito.com/oauth2/token

Ces instructions décrivent comment générer un jeton d’accès dans l’environnement de production. Pour plus d’informations, voir API Megaport.

Remarque

Les points de terminaison API qu’un jeton d’accès peut appeler dépendent du rôle sélectionné pour la clé API lors de sa création. Par exemple, les clés API Read Only (Lecture seule) auront plus de restrictions sur les données accessibles que les clés API Company Admin (Administrateur de l’entreprise).

Pour générer un jeton d’accès dans Postman

Dans la collection Megaport importée dans Postman, cliquez sur l’icône plus pour ajouter une nouvelle demande.
Dans la liste déroulante située à gauche du champ Request URL (URL de demande), sélectionnez POST.
Dans le champ Request URL (URL de demande), saisissez l’URL de demande suivante :
https://auth-m2m.megaport.com/oauth2/token
Sélectionnez l’onglet Authorization (Autorisation) et saisissez les informations de configuration suivantes :
- Username (Nom d’utilisateur) – L’ID client que vous avez copié précédemment lors de la création de la clé API.
- Password (Mot de passe) – Le secret client que vous avez copié précédemment lors de la création de la clé API.
Remarque

Ces paramètres comprennent des données confidentielles. Si vous travaillez dans un environnement collaboratif, il peut être pertinent de définir l’ID client et le secret client sur les variables {{apiKeyClientId}} et {{apiKeyClientSecret}}, respectivement. Pour plus d’informations sur les variables, consultez la documentation de Postman.
Cliquez sur l’onglet Body (Corps) et saisissez une clé appelée grant_type, définie sur la valeur client_credentials.
Cliquez sur Save (Enregistrer).
L’écran Save Request (Enregistrer la demande) s’affiche.
Dans le champ Request name (Nom de la demande), saisissez un nom significatif pour la nouvelle demande.
Par exemple, Générer un jeton d’accès.
(Facultatif) Saisissez une description de la demande.
Sélectionnez l’emplacement auquel vous souhaitez enregistrer la demande, puis cliquez sur Save (Enregistrer).
La nouvelle demande est créée et ajoutée à la collection Documentation API Megaport.
Cliquez sur Send (Envoyer).

Vous devriez recevoir une réponse contenant votre jeton d’accès, similaire à l’exemple ci-dessous. Une fois qu’un jeton d’accès a été généré, il peut être utilisé pour authentifier les utilisateurs d’API pour divers points de terminaison dans le Megaport Portal.
```
 {
  "access_token":  
      "eyJraWQ......2cOQGA",
  "expires_in": 86400,
  "token_type": "Bearer"
 }
```
Copiez le jeton d’accès.
Dans les variables pour la collection (cliquez sur les points de suspension suivant la collection Megaport importée > Edit (Modifier) > Variables), ajoutez une entrée pour access_token et collez le jeton d’accès dans le champ CURRENT VALUE (VALEUR ACTUELLE).
Pour chaque appel API que vous devez envoyer, dans l’onglet Authorization (Autorisation), le Type doit être défini sur Bearer Token (Jeton authentifié) et le champ Token (Jeton) doit être défini sur la variable de jeton d’accès {{access_token}}.

L’appel API est maintenant prêt à être utilisé. Tous les appels API sont effectués via SSL/TLS, et chaque appel est validé par rapport au jeton d’accès pour obtenir les autorisations appropriées.

Remarque

Les jetons d’accès expirent ; vous devez donc générer régulièrement de nouveaux jetons pour vos appels API. Le délai d’expiration est déterminé par la valeur saisie dans le champ Token Expiry (Minutes) (Expiration du jeton (minutes)) lors de la création de la clé API. Le délai d’expiration par défaut est de 24 heures.

Les demandes API comprennent deux paramètres d’en-tête importants : Authorization (Autorisation) et Content-Type (Type de contenu). Le paramètre Authorization (Autorisation) pointe vers l’onglet Authorization (Autorisation), dans lequel la variable du jeton est définie.

En-têtes obligatoires

Génération de jeton via cURL

Pour générer un jeton d’accès, vous pouvez également utiliser cURL via une console de commande au format suivant :

 curl -X "POST" "https://auth-m2m.megaport.com/oauth2/token" \
        -H 'Content-Type: application/x-www-form-urlencoded' \
        -u 'value_of_base64(clientId:clientSecret)_here' \
        --data-urlencode "grant_type=client_credentials"

Conseil

Le site dev.megaport.com vous permet de voir chaque point de terminaison API dans plusieurs langages de programmation.

Dernière mise à jour: 2024-03-13