Authentication

Authentication for the GraphQL API can be performed in one of two ways, either using basic authentication or by generating a JWT token that can be used with subsequent calls.

Basic Authentication

We recommend using an API key for authentication. This can be generated for a user and provided as the password, with the user as the Avantra user ID, when making requests the GraphQL API.

For productive use, we recommend creating a specific user in Avantra that can access only the required information needed for the integration and is not tied to any specific real user account that may be deactivated if that users' roles and permissions change in the future so that the integration continues to work.

API key creation can be performed through the User Management menu item in Administration or through your own profile management for testing/development purposes.

To call an API with an API Key, make a POST call to the API URL:

http[s]://<avantra_ui_hostname>:<avantra_ui_port>/xn/api/graphql

Supply the username and API Key of that user in Basic authentication, meaning an Authorization header containing Basic followed by the base64 encoding of <username>:<api key>.

Set header Content-Type to application/json. Supply the GraphQL query in the query property of the JSON payload for the request.

Example request body:

{"query": "query FetchAllSystem { systems { id name type } }"}

Example response body:

{ "data": { "systems": [ {"id":"544","name":"ADA_MDB","type":"DATABASE"},
                         {"id":"194","name":"ANY_BOL","type":"DATABASE"} ]
          }
}

Generating a token

A token can be generated from an Avantra username and password, and subsequently used to authenticate API calls. Generating a token allows usage of the API in an ordinary logon flow scenario.

First, make a POST call to the token service.

http[s]://<avantra_ui_hostname>:<avantra_ui_port>/xn/api/auth/login

Set header Content-Type to application/json. Supply the Avantra username and password in the JSON payload for the request.

Example request body:

{"username": "user1", "password": "MyPassword123"}

Example response body:

{"username":"user1","token":"TOKEN_VALUE"}

Next, make a POST call to the API.

http[s]://<avantra_ui_hostname>:<avantra_ui_port>/xn/api/graphql

Send the token from the previous response in the Authorization header as a bearer token, Bearer <token>.

Set header Content-Type to application/json. Supply the GraphQL query in the query property of the JSON payload for the request.

Example request body:

{"query": "query FetchAllSystem { systems { id name type } }"}

Example response body:

{ "data": { "systems": [ {"id":"544","name":"ADA_MDB","type":"DATABASE"},
                         {"id":"194","name":"ANY_BOL","type":"DATABASE"} ]
          }
}

Examples of authenticating and using the API

Shell Script

Example shell script using a token. Assumes python3 and curl are available. Save file as run_systems_query.sh, run chmod +x run_systems_query.sh and execute ./run_systems_query.sh <username> <password>.

#!/bin/sh
# Check if username and password were provided
if [ "$#" -ne 2 ]; then
    echo "Usage: $0 username password"
    exit 1
fi

# Assign username and password from script arguments
USERNAME="$1"
PASSWORD="$2"

# Obtain token
TOKEN=$(curl -s -X POST https://pt.avantra.com/xn/api/auth/login \
     -H "Content-Type: application/json" \
     -d "{\"username\": \"$USERNAME\", \"password\": \"$PASSWORD\"}" | python3 -c "import sys, json; print(json.load(sys.stdin)['token'])")

# Check if we got a token
if [ -z "$TOKEN" ]; then
    echo "Failed to obtain token"
    exit 1
fi

# Execute GraphQL query using the obtained token
curl -s -X POST https://pt.avantra.com/xn/api/graphql \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $TOKEN" \
     -d '{"query": "query FetchAllSystem { systems { id name type } }"}'

Python

Example Python program using gql and authenticating with an API Key set on a user.

from gql import gql, Client
from gql.transport.aiohttp import AIOHTTPTransport
import base64

class Avantra:
    def __init__(self, hostname, port, username, apiKey):
        url = f"https://{hostname}:{port}/xn/api/graphql"        

        auth = base64.b64encode(f"{username}:{apiKey}".encode("utf-8")).decode('utf-8')
        authorization = f"Basic {auth}"
        transport = AIOHTTPTransport(url=url, headers={"Authorization": authorization})

        self.client = Client(transport=transport, fetch_schema_from_transport=False)
       
    def execute(self, query, variable_values={}):
        return self.client.execute(gql(query), variable_values)

If above is saved as avantra.py in the same directory as your script.py, you can use the following code:

import avantra
avantraServer = avantra.Avantra("<avantra_ui_hostname>", <avantra_ui_port>",
                                "<username>", "<API Key>")
systems = avantraServer.execute('query FetchAllSystem { systems { id name type } }')

Avantra Javascript Steps and RUN_JS Checks

Example with an Avantra username and API Key stored in a credential with key example.apiCreds.

// Put the GraphQL Query into a JSON structure
var query = {query: "query FetchAllSystem { systems { id name type } }"};

// Call the API
const res = web.request("http[s]://<avantra_ui_hostname>:<avantra_ui_port>/xn/api/graphql")
               .method(web.POST)
               .json(query)
               .useCredentials(monitoredSystem.getCredential("example.apiCreds")
               .fetch();
               
// Variable systems will contain the API response
const systems = res.json;

Example with an Avantra username and password stored in a credential with key example.avantraCreds that generates a token. Requires the Code checkbox on the credential to be ticked.

// Put the GraphQL Query into a JSON structure
var query = {query: "query FetchAllSystem { systems { id name type } }"};

// Get the token
var decryptedCred = monitoredSystem.getCredential("example.avantraCreds").decrypt();
var password = decryptedCred.password;
var username = decryptedCred.username;
var tokenReq = { username: username, password: password }
const resT = web.request("http[s]://<avantra_ui_hostname>:<avantra_ui_port>/xn/api/auth/login")
                .method(web.POST)
                .json(tokenReq)
                .fetch();
var token = resT.json.token;

// Call the API
const res = web.request("http[s]://<avantra_ui_hostname>:<avantra_ui_port>/xn/api/graphql")
               .method(web.POST)
               .json(query)
               .addHeader("Authorization", "Bearer " + token)
               .fetch();
               
// Variable systems will contain the API response
const systems = res.json;