Authentication

IP Fabric accepts 3 different methods of Authentication:

• API Token
• Basic Authentication
• Token Authentication

API Token

Majority of API calls need to be authenticated. API Token needs to be passed as a request header. Please see API Tokens on how to create an API Token in the UI.

Content-Type: application/json
X-API-Token: YOUR_API_TOKEN_GENERATED_VIA_IPFABRIC_UI

Basic Authentication

Using Basic Authentication requires Base64 encoding username:password and passing that into the Authorization header.

osadmin@ipfabric:~$ echo -n "username:password" | base64
dXNlcm5hbWU6cGFzc3dvcmQ=
osadmin@ipfabric:~$ curl -X GET 'https://demo3.ipfabric.io/api/v5.0/snapshots' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' 

Token Authentication

Token Authentication allows a user to submit their Username and Password to the login endpoint which then returns a JSON Web Token (JWT) for them to use in the Authorization header.

Types of Tokens

Access Token

An access token is JSON Web Token (JWT) as per RFC-7519 signed using SHA-256 with RSA encryption.

The token expires in 30 minutes since being generated and it can’t be revoked during its lifetime. It consists of three parts separated by dots:

• Header
• Payload
• Signature

The payload contains an object with the following fields:

• ID - User ID
• EULA - A boolean value whether a user approved EULA or not
• EXP - Token expiration time (in seconds since Unix epoch)
• IAT - Token issued time (in seconds since Unix epoch)
• Scope - Array of strings representing granted user access
• Username - String

Refresh Token

A refresh token is a token that can be used to obtain a renewed access token. It can be requested for new access tokens until the refresh token is revoked (blacklisted) or expired.

Login

To login and obtain an Access and Refresh token please see the below curl example:

curl -X POST 'https://demo3.ipfabric.io/api/v5.0/auth/login' \
  -H 'Content-Type: application/json' \
  --data-raw '{"username":"<USERNAME>","password":"<PASSWORD>"}'

This returns a JSON response with accessToken and refreshToken:

{
  "accessToken": "eyJhbGc...",
  "refreshToken": "YvnTNW..."
}

Using the accessToken

The accessToken is then placed in the Authorization header as seen below. Please ensure it is formatted as Authorization: Bearer <ACCESS_TOKEN>.

curl -X GET 'https://demo3.ipfabric.io/api/v5.0/snapshots' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer eyJhbGc...' 

Using the refreshToken

To create a new accessToken from the refreshToken:

curl -X POST 'https://demo3.ipfabric.io/api/v5.0/auth/token' \
  -H 'Content-Type: application/json' \
  --data-raw '{"refreshToken":"YvnTNW..."}'

Which then returns a new accessToken to use in subsequent calls:

{
  "accessToken": "eyJhbGciOi..."
}

Logout

To logout of IP Fabric:

curl -X POST 'https://demo3.ipfabric.io/api/v5.0/auth/logout' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer eyJhbGc...' 

Changing Default Token Expiration

The default token expiration is as follows:

• accessToken - 30 minutes (1800 seconds)
• refreshToken - 24 hours (86400 seconds)

If the user does any action in the web GUI or requests a new access token using the API within a 24-hour period IP Fabric will keep the user logged in, create a new accessToken, and reset the refreshToken expiration timer for another 24 hours.

Many company standards requires shorter expiration times and this can be accomplished via the CLI settings.

1. Log into IP Fabric CLI as osadmin
2. Elevate to root using sudo -s and osadmin password.
3. Create new file /opt/nimpee/conf.d/api.json with the below JSON 1. In this example the accessToken expires in 10 minutes and refreshToken expires in 15 minutes.

{
  "app": {
    "accessToken": {
      "expiresIn": 600
    },
    "refreshToken": {
      "expiresIn": 900,
      "length": 80
    }
  }
}

1. Change file permissions chmod 644 /opt/nimpee/conf.d/api.json
2. Restart API systemctl restart nimpee-api.service

Token Errors

The API returns an object with a machine-readable error code and a human-readable error message in response body when an error is encountered:

{
  "code": "API_NOT_FOUND",
  "message": "Requested Resource Not Found"
}