Authentication

API Authentication

This page contains detailed options and example code for authenticating to RegScale. The authentication step is necessary to obtain a JSON Web Token (JWT) that provides session access for subsequent API calls. There are multiple options for obtaining a JWT which are discussed on this page.

Authentication via Username and Password

The first method for authenticating to the API is to call the login endpoint at /api/authentication/login. This endpoint allows you to pass a username and password to the endpoint to obtain a JWT. Example code for authenticating is shown in the Python script below:

#!/usr/bin/python
# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth
import json
import argparse

# setup parser for command line arguments
parser = argparse.ArgumentParser(description='Example code for login')
parser.add_argument('--user', metavar='path', type=str, help='RegScale username')
parser.add_argument('--pwd', metavar='path', type=str, help='RegScale password')

# get the argument from the command line
args = parser.parse_args()
if (args.user == ''):
    print('ERROR: No username provided.')
    exit
else:
    strUser = args.user
if (args.pwd == ''):
    print('ERROR: No password provided.')
    exit
else:
    strPWD = args.pwd

# login to your RegScale instance (replace with your URL)
url_login = "https://sandbox.regscale.com/api/authentication/login"

# setup the authentication object
auth = {
    "username": strUser,
    "password": strPWD,
    "oldPassword": ""
}

# login and get token
response = requests.request("POST", url_login, json=auth)
authResponse = response.json()
# capture the user ID (GUID)
userId = authResponse["id"]
#set the token in the header
jwt = "Bearer " + authResponse["auth_token"]
headers = {
   'Authorization': jwt
}

This script takes the username and password from the command line, creates an object to pass to the login endpoint, and captures the JSON response which is used to establish the username and JWT bearer token for future API calls.

Copy and Paste

The second method for getting a JWT token for authenticating APIs is to copy and paste it from your user profile in RegScale. To get your existing token, click your name in the top right and select "My Profile". Navigate below the toolbar and you will see the "Current Access Token" shown; see screenshot below:

If you click the "copy" icon on the screen above, it will automatically paste your token to your clipboard where you can paste it in your code or API call. This token has the same permissions as the logged in user and the token may be used for up to 24 hours before timing out.

Service Accounts

The last method is to setup a service account. This method is to support long running tokens that may be used for integrations with other systems. Each token must be created by an Administrator using the Admin panel under "Setup". The token can have a specific duration set, will have the Administrator role/privileges, and multiple tokens can be created for different purposes. You can create unlimited service accounts and they do not require additional user licensing.

The first step is to create a service account as shown in the screenshot below:

Each service account must be given a duration for which it is valid and should describe its intended purpose. Once the account is created, you can click the "Copy Token" button to add the token to your clipboard where you can paste it into your code or key vault for later use.