Authentication

Audience

This is aimed at NetFoundry customers and trial users who will use the API directly to augment and automate their use of the NF Console.

Overview

All authenticated operations require an HTTP header like

Authorization: Bearer {NETFOUNDRY_API_TOKEN}

where {NETFOUNDRY_API_TOKEN} is an expiring JSON Web Token (JWT) that you obtain from Cognito, NetFoundry API’s identity provider, by authenticating with your API account.

Step by Step

Get an API Account

  1. Start a free trial if you need a login for NF Console
  2. Log in to NF Console
  3. In NF Console, navigate to “Organization”, “Manage API Account”, and click
  4. Make a note of the three values shown: CLIENT_ID, PASSWORD, OAUTH_URL

Get an Access Token

Use your API account (clientId, password, authenticationUrl) to obtain a temporary access_token from the identity provider. Here are examples for HTTPie and cURL to get you started.

HTTPie

❯ http --form --auth "${NETFOUNDRY_CLIENT_ID}:${NETFOUNDRY_PASSWORD}" \
    POST ${NETFOUNDRY_OAUTH_URL} \
    "scope=https://gateway.production.netfoundry.io//ignore-scope" \
    "grant_type=client_credentials"

cURL

❯ curl --user ${NETFOUNDRY_CLIENT_ID}:${NETFOUNDRY_PASSWORD} \
    --request POST ${NETFOUNDRY_OAUTH_URL} \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data 'grant_type=client_credentials&scope=https%3A%2F%2Fgateway.sandbox.netfoundry.io%2F%2Fignore-scope'

Send a Request to the NetFoundry API

Include the expiring bearer token in your request to the NetFoundry API. You could source the shell script below to make NETFOUNDRY_API_TOKEN available.

HTTPie

❯ http GET https://gateway.production.netfoundry.io/rest/v1/networks \
  "Authorization: Bearer ${NETFOUNDRY_API_TOKEN}"

cURL

❯ curl https://gateway.production.netfoundry.io/rest/v1/networks \
    --header "Authorization: Bearer ${NETFOUNDRY_API_TOKEN}"

Script

Pull it all together with HTTPie (command-line HTTP client) and jq (command-line JSON processor).

export  NETFOUNDRY_CLIENT_ID=1st50d7si3dnu275bck2bd228m \
          NETFOUNDRY_PASSWORD=1lhfgel7fi048nabt0f74ghckqbj5lsbmqa1g101ud9a935edhv8 \
          NETFOUNDRY_OAUTH_URL=https://netfoundry-sandbox-hnssty.auth.us-east-1.amazoncognito.com/oauth2/token
❯ source ./export-netfoundry-api-token.bash

Download export-netfoundry-api-token.bash