The Pureport REST API exposes all of the power of the Pureport platform via an easy-to-use REST API. This allows Pureport networks to easily be created or modified as part of a CI/CD workflow, or included in ad-hoc automation scripts.
Create an Account
Before you can use the API, you must have a Pureport account with a valid payment method setup. If your organization doesn't have an account yet, you can easily create one using our via the Pureport console by going to https://console.pureport.com.
You can also create child accounts as needed to keep your networks separate between teams and/or environments, while still sharing a single parent billing account. For example, you may want child accounts for development, QA, staging, and production environments.
Create an API Key
Before you can call the API, you must first create an API key to use for authenticating. An API key consists of a key/secret pair, and is tied to one or more roles for a given account. It's a good idea to limit the roles that are granted to an API key to only those that are needed for your script or application to do what it needs to do.
- Login to the Pureport Console
- Select the account that you want to create an API key for. Note: API Keys defined on parent accounts can be used for all child accounts.
- If needed, create a new Role for the API key that contains only the permissions required for your script or application to operate.
- Navigate to the API Keys page.
- Click the '+' button to create a new API Key.
- Enter a descriptive name for the key (e.g. 'my-app-prod-key') and select the role(s) that should be assigned to the key.
- Record the generated key and secret. The secret will only be returned once, so make sure you capture it! If you lose the secret, you will need to create a new API key.
Authenticate
Before you can make other calls to the API, you must first exchange your API key for a temporary access token by making an HTTP POST
request to the /login
endpoint. Here's an example:
curl -X POST -H "Content-Type: application/json" -d '{
"key": "MY_API_KEY",
"secret": "MY_API_SECRET"
}' https://api.pureport.com/login
If your supplied key/secret are valid, then an OAuth 2.0 Access Token Response will be returned containing an access token that is valid for 1 hour.
Note: If you need to interact with the API for longer than 1 hour, you will need to re-authenticate to get a new access token at least once per hour.
Here's an example of an access token response:
HTTP/1.1 200 Success
{
"access_token": "MY_ACCESS_TOKEN",
"token_type": "bearer",
"expires_in": 3600
}
Per RFC 6750, the returned access token should then be included as a "bearer" token in the Authorization header on subsequent requests.
Here's an example showing how to list your accounts with the Authorization header included.
curl -H "Authorization: Bearer MY_ACCESS_TOKEN" https://api.pureport.com/accounts
Create a Network
Now that you're authenticated, let's try creating a new network.
Following the REST convention, to create a network, you will POST
some JSON to the /accounts/{accountId}/networks
resource path, where the target account's ID is included as a path parameter. The ID of the target account can be found in the response from the previous example where we listed the accounts by accessing https://api.pureport.com/accounts
In this example, we are adding a network called "My New Network" to the account with a ID of "ac-1234". The only required parameter for creating a network is the name.
Request:
curl -H "Authorization: Bearer MY_ACCESS_TOKEN" -H "Content-Type: application/json" -d '{
"name": "My New Network"
}' https://api.pureport.com/accounts/ac-1234/networks
Response:
HTTP/1.1 201 Created
Location: https://api.pureport.com/networks/net-5678
{
"id": "net-1234"
"name": "My New Network"
}
In our example, the resulting network will then be available at https://api.pureport.com/networks/net-5678
as indicated by the Location
response header.
Add a Connection (AWS Direct Connect)
Let's keep going and add an AWS Direct Connect connection to our network by issuing a 'POST' request to /networks/net-5678/connections
Request:
curl -H "Authorization: Bearer MY_ACCESS_TOKEN" -H "Content-Type: application/json" -d '{
"type": "AWS_DIRECT_CONNECT",
"location": {
"id": "us-ral",
"href: "/locations/us-ral"
},
"awsAccountId": "123456789",
"awgRegion": "us-east-1",
"highAvailability": true,
"speed": "MBPS_100"
}' https://api.pureport.com/networks/net-5678/connections
Note: To complete the connection process, you will need to accept the Virtual Interface via the AWS Console, CLI, or API after creating the connection via the Pureport API.
Delete Network
After we're done playing around, we can delete the network (and it's associated connections), by issuing a DELETE
request to the network's path.
curl -X DELETE -H "Authorization: Bearer MY_ACCESS_TOKEN" https://api.pureport.com/networks/net-5678
Keep Learning
Now that you know the basics, head on over to the API Reference Docs in the Pureport Console to learn more about what's possible with the Pureport API.