The Pureport API : Pureport

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.

The Pureport API