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.

RapidAPI subscribers will use their RapidAPI token with the RapidAPI code samples instead of an Auth0 credential.

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 Auth0, NetFoundry API’s identity provider, by authenticating with your permanent credential.

Shell example

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

source export-netfoundry-api-token.bash

download this example

# source this file in bash or zsh to make
#  NETFOUNDRY_API_TOKEN 
# available to processes run in the same shell

_get_nf_token(){
    set -o pipefail
    [[ $# -ge 2 ]] || {
        echo "ERROR: send two params: client_id client_secret" >&2
        return 1
    }
    client_id=$1
    client_secret=$2
    env=${3:-production}
    access_token=$(
    http --check-status \
      POST https://netfoundry-${env}.auth0.com/oauth/token \
        "client_id=${client_id}" \
        "client_secret=${client_secret}" \
        "audience=https://gateway.${env}.netfoundry.io/" \
        "grant_type=client_credentials" | \
            jq -r .access_token
    ) || return 1
    echo ${access_token}
}

[[ ! -z ${NETFOUNDRY_CLIENT_ID:-} && ! -z ${NETFOUNDRY_CLIENT_SECRET:-} ]] || {
    echo "ERROR: permanent credential vars NETFOUNDRY_CLIENT_ID, NETFOUNDRY_CLIENT_SECRET are not assigned" >&2
    return 1
}

NETFOUNDRY_API_TOKEN=$(_get_nf_token ${NETFOUNDRY_CLIENT_ID} ${NETFOUNDRY_CLIENT_SECRET})

[[ ${NETFOUNDRY_API_TOKEN} =~ ^[A-Za-z0-9_=-]+\.[A-Za-z0-9_=-]+\.?[A-Za-z0-9_.+/=-]*$ ]] && {
    export NETFOUNDRY_API_TOKEN
} || {
    echo "ERROR: invalid JWT for NETFOUNDRY_API_TOKEN: '${NETFOUNDRY_API_TOKEN}'" >&2
    return 1
}

 

Step by Step

Get a permanent credential

  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

Get a temporary token

Use your permanent credential; client_id, client_secret; to obtain an expiring access_token from the identity provider, Auth0. Here are examples for curl and http to get you started.

HTTPie

❯ http POST https://netfoundry-production.auth0.com/oauth/token \
  "client_id=${NETFOUNDRY_CLIENT_ID}" \
  "client_secret=${NETFOUNDRY_CLIENT_SECRET}" \
  "audience=https://gateway.production.netfoundry.io/" \
  "grant_type=client_credentials"

cURL

❯ curl \
    --silent \
    --show-error \
    --request POST \
    --header 'content-type: application/json' \
    --data '{
        "client_id": "'${NETFOUNDRY_CLIENT_ID}'",
        "client_secret": "'${NETFOUNDRY_CLIENT_SECRET}'",  
        "audience": "https://gateway.production.netfoundry.io/",
        "grant_type": "client_credentials"
    }' \
    https://netfoundry-production.auth0.com/oauth/token

Use the token with an API operation

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

HTTPie

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

cURL

❯ curl \
    --silent \
    --show-error \
    --request GET \
    --header "Authorization: Bearer ${NETFOUNDRY_API_TOKEN}" \
    https://gateway.production.netfoundry.io/core/v2/networks