IPFabric API (v1)

API Endpoint

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC-2119.

URL Prefix

API URL has the following structure:

https://<hostname>/api/v1/<endpoint>

Status Codes

This API uses HTTP status codes to communicate with the API consumer.

200 OK - response to a successful GET, PUT, PATCH or DELETE request,
201 Created - response to a POST request that results in the creation of a resource,
204 No Content - response to a successful request that won’t be returning a body,
400 Bad Request - response to a request that is malformed or it does not follow this documentation,
401 Unauthorized - response to a request with invalid authentication details,
403 Forbidden - response to a request made by an authenticated user but with no access to the requested resource,
404 Not Found - response to request a non-existing endpoint or resource,
405 Method Not Allowed - response to requesting an existing endpoint that does not support the used method,
406 Not Acceptable - response to a request that could not satisfy the Accept header,
409 Conflict - response to a request that causes a conflict with the current state of the target resource.
422 Unprocessable Entity - response to a request that provided invalid input to the existing endpoint.
429 Too Many Requests - response after too many requests are sent from the same IP address in one second.
500 Internal Server Error - response to a request that caused an unexpected behaviour.

Authentication

The API offers three HTTP authentication methods:

API keys,
Basic authentication,
Token authentication.

API Keys

Using API keys is the preferred way of authenticating when working with the API programatically.

Any user can define an API key in the product administration. Please note that the token string is visible / editable only when you create the token, you will not see it or be able to modify it later on. For this reason, please make sure you copy the token string when creating the API token in the UI.

An API key can’t have stronger permissions[?] than its owner. Administrators have access to remove / change permissions of all API keys in the system.

A request must contain a header field X-API-Token: <string>.

Basic Authentication

Basic HTTP Authentication as per RFC-7617 (excluding Digest) is supported. A request contains a header field of the form Authorization: Basic <credentials>, where credentials is the Base64 encoding of username and password joined by a colon character. It is RECOMMENDED to use this authentication method only for API exploration/testing since the API has to fetch user data from a database on every single request.

Token Authentication

A request contains a header field of the form Authorization: Bearer <token>, where token is the access token:

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 - a user ID,
eula - a boolean value whether a user approved EULA or not,
exp - a token expiration time (in seconds since Unix epoch),
iat - a token issued time (in seconds since Unix epoch),
scope - an array of strings representing granted user access (more in authorization),
username - a 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. A refresh token expires after 24 hours of not being used for generation of a new access token.

Refresh tokens must be stored securely by an application because they essentially allow a user to remain authenticated forever.

Token Authentication Flow

Login user (more).
Safely store a refresh token and use an access token in any requests that require authentication.
When a request returns API_EXPIRED_ACCESS_TOKEN error, get a new access token using the stored refresh token (more).
Repeat steps 2-4 until the refresh token is valid. If the refresh token expires, new login is necessary.

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"
}

Common Errors

API_EXPIRED_API_TOKEN - The provided API key expired.
API_INVALID_API_TOKEN - The provided API key doesn’t exist. It was removed, or it never existed.
API_MISSING_EULA_APPROVAL - This error occurs when a user hasn’t approved EULA. It is REQUIRED to login using the user’s credentials into the application user interface and accept EULA.
API_EXPIRED_ACCESS_TOKEN - The provided access token (from Authorization header) is expired.
API_INVALID_ACCESS_TOKEN - The provided access token (from Authorization header) is invalid.
API_INVALID_REFRESH_TOKEN - The provided refresh token (typically sent in the request body) is revoked (blacklisted) or expired.
API_NOT_FOUND - The requested resource does not exist.

Authorization

Every API key / user has its granted scope that allows it to access a different part of the application. The available access scope follows:

scope name	description
read	Access to read-only data
settings	Right to change global settings
team	Access into user management
write	Right to start network discovery process

If an user does not have any granted authorization scope, he is considered inactive, and he is unable to log into the system. It is recommended to choose the most restrictive scopes possible to any user.

Authentication ¶

POST /auth/login

RequestsExample

Body

{
  "username": "admin",
  "password": "password"
}

Schema

{
  "type": "object",
  "properties": {
    "username": {
      "type": "string"
    },
    "password": {
      "type": "string"
    }
  },
  "required": [
    "username",
    "password"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Responses200401

Headers

Content-Type: application/json

Body

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eGdOyqN-VUPhSvnQv54BHQaA9vcr_UliFYGi..."
}

Headers

Content-Type: application/json

Body

{
  "code": "API_INVALID_CREDENTIALS",
  "message": "Invalid Credentials"
}

Token Actions ¶

POST /auth/token

RequestsExample

Body

{
  "refreshToken": "eGdOyqN-VUPhSvnQv54BHQaA9vcr_UliFYGi..."
}

Schema

{
  "type": "object",
  "properties": {
    "refreshToken": {
      "type": "string"
    }
  },
  "required": [
    "refreshToken"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Responses200401

Headers

Content-Type: application/json

Body

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Headers

Content-Type: application/json

Body

{
  "code": "API_INVALID_REFRESH_TOKEN",
  "message": "Invalid Refresh Token"
}

Generate Access Token
POST`/auth/token`

Generate an access token using a refresh token.

DELETE /auth/token

RequestsExample

Headers

Content-Type: application/json
Authorization: <data>

Body

{
  "refreshToken": "eGdOyqN-VUPhSvnQv54BHQaA9vcr_UliFYGi..."
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "refreshToken": {
      "type": "string"
    }
  },
  "required": [
    "refreshToken"
  ]
}

Responses204401

This response has no content.

Headers

Content-Type: text/plain

Body

Unauthorized

Revoke Refresh Token
DELETE`/auth/token`

Only an authorized user with team scope can revoke a refresh token.

Logout User ¶

POST /auth/logout

RequestsExample

Headers

Content-Type: application/json
Authorization: <data>

Responses200401

Headers

Content-Type: application/json

Body

{
  "success": true
}

Headers

Content-Type: application/json

Body

{
  "code": "API_EXPIRED_ACCESS_TOKEN",
  "message": "Expired JWT Access Token"
}

Logout User
POST`/auth/logout`

Only an authorized user can log out.

Tables ¶

Table documentation can be found directly in the platform by clicking on the question mark button in the header of a table. The documentation contains an API endpoint and an object structure required for a successful request. It also contains a request body of a current table state.

A request body used by the platform to retrieve table data can be seen by clicking on the “Table description” button in the header of a table.

Request Payload

A JSON object with the following properties:

snapshot [required]: a string with a snapshot ID or one of the following variables:
- $last: the latest snapshot,
- $prev: the second last snapshot,
- $lastLocked: the latest locked snapshot,
columns [required]: an array of strings representing data that should be retrieved (more info),
filters [optional]: more info,
pagination [optional]: more info,
sort [optional]: more info,
reports [optional]: more info.

Columns

An array of strings that represents fields for each record that should be returned. Only the listed fields are returned.

Filter Structure

A filter object is an object with the following structure:

{
    [column]: [<operator>, <value>],
    "or": <array of filter objects>,
    "and": <array of filter objects>
}

An example of a filter is:

{
    "vendor": ["eq", "cisco"],
    "or": [
        {"hostname": ["eq", "HWLAB-01"]},
        {"hostname": ["eq", "HWLAB-02"]},
    ]
}

Pagination

An optional object that contains number of records to be returned (limit) and an offset (start).

The following example returns 10 records starting from 20th record.

{
    "limit": 10,
    "start": 10
}

Sort

An optional object that contains a column that is being sorted on and an order (asc for asceding or desc for descending order).

Example:

{
    "column": "uptime",
    "order": "desc"
}

Reports

The reports property accepts two data types:

an array of colour report IDs,
a string of frontend URL where the reports are displayed (for example "/inventory/devices" for Inventory/Devices table).

If a valid value is specified, the response for a particular column returns data in a form of {"data": "value", "severity": 0}, where severity can either be:

0 - green colour,
10 - blue colour,
20 - yellow colour,
30 - red colour.

Generated by aglio on 12 Apr 2022

API Endpoint

URL Prefix ¶

Status Codes ¶

Authentication ¶

API Keys ¶

Basic Authentication ¶

Token Authentication ¶

Access Token ¶

Refresh Token ¶

Token Authentication Flow ¶

Errors ¶

Common Errors ¶

Authorization ¶

Authentication ¶

Login User ¶

Body

Schema

Headers

Body

Headers

Body

Retrieve Refresh and Access TokenPOST/auth/login

Token Actions ¶

Body

Schema

Headers

Body

Headers

Body

Generate Access TokenPOST/auth/token

Headers

Body

Schema

Headers

Body

Revoke Refresh TokenDELETE/auth/token

Logout User ¶

Headers

Headers

Body

Headers

Body

Logout UserPOST/auth/logout

Tables ¶

Request Payload ¶

Columns ¶

Filter Structure ¶

Pagination ¶

Sort ¶

Reports ¶

URL Prefix

Status Codes

Authentication

API Keys

Basic Authentication

Token Authentication

Access Token

Refresh Token

Token Authentication Flow

Errors

Common Errors

Authorization

Retrieve Refresh and Access Token
POST`/auth/login`

Generate Access Token
POST`/auth/token`

Revoke Refresh Token
DELETE`/auth/token`

Logout User
POST`/auth/logout`

Request Payload

Columns

Filter Structure

Pagination

Sort

Reports