Using Postman with the PacketFabric API

API requests typically return more information than is visible in the portal. This can be helpful when troubleshooting issues.

If you do not already have Postman installed, you can download it here: https://www.postman.com/downloads/

API authentication

All your API requests need to be authenticated with a bearer token. Tokens are unique to a session.

When you use the login endpoint to get your token, you also terminate any other active sessions tied to your account.

This means that you will be prompted to log in to the portal when you return. Similarly, if you log in to the portal, you will need to retrieve a new token next time you send an API request through Postman.

Retrieve your bearer token

  1. Open Postman and click the plus icon to add a new request.

    Add new request button in Postman

  2. Select POST from the drop-down menu that appears before the URL field.

    Postman request types

  3. Enter the following request URL: https://api-beta.packetfabric.com/v2/auth/login

  4. Select the Body sub-tab and then select raw. From the drop-down menu to the right, select JSON.

    Request body for login

  5. In the space below, enter your username and password in the following format (include the curly brackets):

    {
      "login": "caitlin@packetfabric.com",
      "password": "iloveknowledgebases!"
    }
    NOTE: Enter your username and password in plain text. As soon as you send your request, your credentials will be encrypted using SSL.
  6. Click Send.

  7. You should receive a response that includes your token.

    Example token return

  8. Copy the token to your clipboard.

Every request you send to the PacketFabric API must include a token. See Create and send a request below for details on how to include the token in requests.

Submit a multi-factor authentication code

If you have two factor authentication enabled, you will be prompted to enter a code.

  1. Complete the steps above to retrieve your bearer token.

  2. Using the same request form, click the Authorization tab.

  3. From the Type drop-down menu, select Bearer Token.

  4. Paste your token into the field provided.

    Authorization tab

  5. Add the mfa endpoint to the request URL: https://api-beta.packetfabric.com/v2/auth/login/mfa

  6. Select the Body sub-tab and replace your username and password with your authentication code (enclosed in quotation marks):

    {
      "authentication_code": "123456"
    }
  7. This should return a simple success message, and then you can begin sending other requests.

Create and send a request

  1. Click the plus icon to open a new request form.

  2. Click the Authorization tab.

  3. From the Type drop-down menu, select Bearer Token.

  4. Paste your token into the field provided.

    Authorization tab

    TIP: If you will be using Postman frequently with our API, you can create a collection in which the token is automatically added to all new requests.

    This also means that when you need to retrieve a new token, you only need to update it in one location. For more information, see the Postman documentation on creating collections.

  5. Review our API reference to find the request you would like to send.

  6. Click the drop-down menu next to the request name. Copy the URL.

    API ref down arrow

  7. Paste the PacketFabric URL into the request form.

  8. If the URL contains a parameter (indicated by curly braces), replace it with the appropriate information.

    Many APIs require an identifier such as a circuit ID. If you don’t know the ID, you can find it in two places:

    • Use the API - There are several APIs that return device or service lists. For example, the ports request returns a list of your ports, which includes all their circuit IDs.

    • Use the portal - Circuit IDs can be found on service details pages. They start with PF and are followed by the service type, POP, and a numeric ID. For a list of service type acronyms in circuit IDs, see the PacketFabric FAQ.

      However, note that if you sign in to the portal to get the circuit ID, you will need to retrieve a fresh token in Postman when you return.

  9. Click Send.

“Not authorized” error

If your request returns with a “not authorized” error, the most likely reason is that your token is no longer valid. This can happen if you have logged in to the portal or have used the login endpoint elsewhere.

To fix this, you just need to generate a new token.

If you are still receiving that error with a fresh token, you might not have permission to complete the API request. For more information on what actions users can take, see User Permissions.

“Invalid value” error

This is typically due to entering a string parameter in the JSON body without enclosing it in quotes. Boolean (true/false) and integers do not need surrounding quotes.

For example, the API call to create a dedicated Google connection includes strings, a boolean value, and an integer.

{
  "account_uuid": "a2115890-ed02-4795-a6dd-c485bec3529c",
  "description": "Connection for uploading cute cat pics",
  "zone": "A",
  "pop": "DAL1",
  "subscription_term": 24,
  "service_class": "longhaul",
  "autoneg": false,
  "speed": "10Gbps"
}

Our API reference lists each parameter type:

screenshot of reference docs with the param type highlighted