Authentication

Liongard supports authentication to the API via API keys generated for a user created specifically for the integration.

Liongard utilizes the "Basic Auth" standard with Public and Private keys. The authorization header is unique to Liongard users, meaning you can use the benefits of Liongard security roles and give granular access to the APIs.

In order to authenticate with the Liongard API, you must generate an API key in your Liongard instance.

Steps to Authenticate

  1. Generate your API Keys
  2. Format your Request Headers
  3. Test your Credentials

Important Note: SSL is required on all calls when accessing the API. Any calls received via regular HTTP will be automatically forwarded to HTTPS.

Obtaining API Keys

  1. Log in to your Liongard instance.
  2. Click on the profile drop-down in the upper-right hand corner of the navigation bar.
  3. Click on Account Settings.

  1. Select the Access Tokens tab
  2. Click on the "Generate New Token" button.

  1. Copy the Access Key ID and Access Key Secret. Please note that the Access Key Secret will no longer be visible once you navigate away from the page.

Obtaining API Keys Programmatically

  1. Make a POST request to the [authentication/login] (https://docs.liongard.com/reference/login-1) endpoint with the username and password of the account the API Keys should belong to.
  2. Retrieve the session token from the "token" property from the response.
  3. If MFA is enabled, make a POST request to the [authentication/verify-token] (https://docs.liongard.com/reference/verifytoken) endpoint with the following header and retrieve the new session token from the "token" property from the response:
  • Key = X-Auth-Token
  • Value = session token
  1. Make a POST request to the [access-keys] (https://docs.liongard.com/reference/createaccesskey) endpoint with the following header:
  • Key = X-Auth-Token
  • Value = session token
  1. Copy the AccessKeyID and AccessKeySecret from the response.

πŸ“˜

Following Forwards

In order to use the Liongard API, you must be able to automatically follow forwards (HTTP 301 Responses). All API requests return a 301 request initially as they are automatically forwarded to the API for security reasons.

Authentication/Request Headers

All API requests require the following headers:

  • Key = X-ROAR-API-KEY
  • Value = base 64 encoding of access key:access secret

πŸ“˜

Enhancing API Integration Identification with User-Agent Header

In order to help Liongard identify your API integration it is recommended that you add the optional User-Agent header. This allows Liongard to differentiate your integration and better serve you.

You can implement this optional header by setting the key as User-Agent and setting the value with the following format: <Vendor-Name>/<IntegrationVersion>

An example of this could be: User-Agent: Brightgauge/1.0

Testing Credentials

To test that your API Key and Secret are working, you can do a simple request from the command line.

# Replace the XXX with your access key and secret and instance name
KEY=XXX
SECRET=XXX
TOKEN=$(echo -n "$KEY:$SECRET" | base64)
curl https://XXX.app.liongard.com/api/v1/environments/count/ -H "X-ROAR-API-KEY: $TOKEN"
$Key = "XXX"
$Secret = "XXX"
$Bytes = [System.Text.Encoding]::UTF8.GetBytes("$($Key):$($Secret)")
$EncodedText =[Convert]::ToBase64String($Bytes)
Invoke-WebRequest -Uri https://XXX.app.liongard.com/api/v1/environments/count/ -Headers @{"X-ROAR-API-KEY"="$($EncodedText)"}

πŸ‘

Next

Using the Liongard v1 API