Creating an API Key

Megaport API calls require an access token that you can generate after creating an API key. An access token is required for authenticating API users, and allows temporary access to only the parts of the Megaport Portal that are required.

It is recommended that a machine to machine (M2M) company admin account be created for accessing the Megaport API and creating API keys. In the event that a human user is deactivated or locked out of their account, the API keys created by that user will also be suspended, which might stop any API integrations from working.

API keys are valid only in the environment in which they were generated. If you need API keys to access a different environment, log in to the Megaport Portal in that environment and generate the API keys there.

Note

You must be logged in to the Megaport Portal as a user with the Company Admin role to create an API key. For more information, see Managing User Roles.
A maximum of five API keys can be created per company.

This topic describes the following tasks:

To create an API key in the Megaport Portal
To generate an access token in Postman

To create an API key in the Megaport Portal

In the Megaport Portal, choose Tools > API Key Generator.
The API Keys screen allows you to create API keys, and to view and edit existing API keys.
Specify the details for the API key.
- Name – Enter a name for the API key.
  This should be a descriptive name to identify the purpose of the key.
  Note
  - A minimum of three characters is required for the API key name.
  - No special characters are allowed except for dash and hyphen.
- Role – Select the role of the user who will be using the API.
  The following options are available:
  - Company Admin
  - Read Only
- Token Expiry (Minutes) – Enter the amount of time (in minutes) after which the token generated from this key will expire. The minimum is 5 minutes and the maximum is 24 hours (1440 minutes). After the token expires, you need to generate a new access token.
Click Generate Key.
The API key is created and the Your API Key prompt appears.

Important

Copy your new API Key and API Key Secret, and store these credentials somewhere secure. You will need to use them to generate access tokens. Make sure you copy the API Key Secret because it won’t be shown again after you close this prompt.
Click Copy to the right of the API Key field and paste the key (Client Id) in a safe place.
Click Copy to the right of the API Key Secret field and paste the Client secret in a safe place.
Click Close.
The API key is created and displayed in the Active API Keys area of the screen.
In the Active API Keys area, you can edit the name of the key, delete the key, and view the history of changes that have occurred for the key.

Generating an access token

After you have created the API key, consisting of a client ID and client secret, you can generate an access token for authenticating API users. These instructions describe how you can do this using Postman and the Megaport collection. For Postman setup details, see Megaport API.

The request URL that you need to use depends on the environment in which you are generating an access token. In each environment, these request URLs should be used:

Production environment: - https://auth-m2m.megaport.com/oauth2/token
Staging (test) environment: - https://oauth-m2m-staging.auth.ap-southeast-2.amazoncognito.com/oauth2/token

These instructions describe how to generate an access token in the Production environment. For more information, see Megaport API and Megaport Authentication - API Keys.

Note

Which API endpoints an access token can call depends on the role selected for the API key when it was created. For example, Read Only API keys will have more restrictions on the data that can be accessed than Company Admin API keys.

To generate an access token in Postman

In the imported Megaport collection in Postman, click the plus icon to add a new request.
In the drop-down list to the left of the Request URL field, select POST.
In the Request URL field, enter the following request URL:
https://auth-m2m.megaport.com/oauth2/token
Select the Authorization tab and enter the following parameter details:
- Username – The client ID that you copied earlier when creating the API key.
- Password – The client secret that you copied earlier when creating the API key.
Note

These parameters contain sensitive data. If you are working in a collaborative environment, you might want to set the client ID and client secret as the variables {{apiKeyClientId}} and {{apiKeyClientSecret}} respectively. For more information on variables, see the Postman documentation.
Click the Body tab and enter a key called grant_type which is set to a value of client_credentials.
Click Save.
The Save Request screen appears.
In the Request name field, enter a meaningful name for the new request.
For example, Generate Access Token.
(Optional) Enter a description of the request.
Select where you would like to save the request then click Save.
The new request is created and added to the Megaport API Documentation collection.
Click Send.

You should receive a response that includes your access token, similar to the example below. Once an access token is generated, it can be used to authenticate API users for various endpoints in the Megaport Portal.
```
 {
  "access_token":  
      "eyJraWQ......2cOQGA",
  "expires_in": 86400,
  "token_type": "Bearer"
 }
```
Copy the access token.
In the variables for the collection (click the three dots after the imported Megaport collection > Edit > Variables), add an entry for access_token and paste the access token into the CURRENT VALUE field.
For each API call that you need to send, in the Authorization tab, the Type should be set to Bearer Token and the Token should be set to the access token variable {{access_token}}.

The API call is now ready to use. All API calls are made over SSL/TLS, and every call is validated against the access token for appropriate permissions.

Note

Access tokens will expire so you need to regularly generate new tokens for your API calls. The expiry period is determined by the value that was entered for the Token Expiry (Minutes) field when the API key was created. The default expiry period is 24 hours.

API requests include two important header parameters: Authorization and Content-Type. The Authorization parameter points to the Authorization tab where the token variable is set.

Required headers

cURL token generation

Another way to generate an access token is using cURL from a command console in the following format:

 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"

Tip

The dev.megaport.com site lets you see each API endpoint in multiple programming languages.

Last update: 2024-04-15