Skip to content
  • There are no suggestions because the search field is empty.

API: Authentication

The following article covers how to authenticate prior to using the API.

To use the API, first use the /Authenticate operation to retrieve an authentication token.

You should provide the username and password for a user registered on the site. All operations of the API will be limited by the access rights of the user.

For all future requests, Basic Authentication is required.

The username for basic authentication should be the user’s username, and the password should be the API authentication token retrieved from the /Authenticate operation.

🚨Note:  For sites with SSO enabled (i.e. you have a custom authentication portal or identity provider), you need to set a password (through the administration area) for each user which will use the API. This password is not synced with the authentication portal, and will only be used for the API authentication.

See the following guidance on authenticating using: 

Bash

#!/bin/bash
baseUrl=$1
username=$2
password=$3
  
# GET method is deprecated use POST method,using Get the auth token and pipe through jq to deserialize the JSON (and select the current node which is a string)
# authToken=$(curl -s -d username=$username -d password=$password -H "accept: application/json" -G "${baseUrl}api/v1/authenticate" | jq -r '.')  

# for POST Create JSON data 
json_data='{"username":"'"$username"'","password":"'"$password"'"}'  

# Make the POST request 
authToken=$(curl -s -X POST -H "accept: application/json" -d "$json_data" "${baseUrl}/api/v1/authenticate" | jq -r '.')  

# Create the auth header by base 64 encoding 
# This can be cached for up to an hour but not done here for brevity 
authHeader=$(echo -n "${username}:${authToken}" | base64)  

# Perform an authenticated GET to ~/api/v1/products, using jq to filter JSON to just product codes. 
curl -s -d Take=10000 -H  "accept: application/json" -H  "Authorization: Basic $authHeader" -G "${baseUrl}api/v1/products" | jq -r '.products[].productCode'

C#

using System; 
using System.Collections.Generic; 
using System.Linq; using System.Text; 
using IO.Swagger.v1.Api; 
using IO.Swagger.v1.Client; 
using Newtonsoft.Json; 
using Domain;  

/// <summary> 
/// Authenticates as the user specified by <paramref name="username"/> and retrieves all product codes (up to the first 10,000) to prove they can access the API. 
/// </summary> 
public static List<string> GetProductCodes(string baseUrl, string username, string password) 
{     
// Make the swagger configuration object with just base url.     
// This will mean operations are unauthenticated by default     
var configuration = new Configuration     
{        
 BasePath = baseUrl     
};      

// Get the token and encode it.     
// This can be cached for up to an hour, but not done here for brevity     
var authClient = new AuthenticationApi(configuration);      

// GET method deprecated use POST Method, Normally responses are automatically deserialzed, but this client doesn't deserialize plain strings correctly, so pass through JSON.NET for correct handling.     
// var authenticationToken = JsonConvert.DeserializeObject<string>(authClient.AuthenticateGet(username, password));      

// POST method, Normally responses are automatically deserialzed, but this client doesn't deserialize plain strings correctly, so pass through JSON.NET for correct handling.     
var userAuthentication = new UserAuthentication(username, password);     
var authenticationToken = JsonConvert.DeserializeObject<string>(authClient.AuthenticatePost(userAuthentication));
      
// Add the basic authentication header to all future requests     
var encodedToken = Convert.ToBase64String(Encoding.UTF8.GetBytes(username + ":" + authenticationToken));
configuration.AddDefaultHeader("Authorization", "Basic " + encodedToken);      

// Perform an authenticated GET to ~/api/v1/products and filter to just product codes     
var productsClient = new ProductsApi(configuration);    
return productsClient.ProductsGet(take: 10_000).Products.Select(p => p.ProductCode).ToList(); 
}

 

PowerShell

Param (     
[Parameter(Mandatory=$true)][ValidateNotNullOrEmpty()][string] $baseUrl,     
[Parameter(Mandatory=$true)][ValidateNotNullOrEmpty()][string] $username,     
[Parameter(Mandatory=$true)][ValidateNotNullOrEmpty()][string] $password 

) 
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]" 
$headers.Add("Content-Type", "application/json") 
 
$body = @{     
username = $username     
password = $password } | ConvertTo-Json 
 
# GET method is deprecated use POST method 
# $token = Invoke-RestMethod -Method Get -Uri "$($baseUrl)api/v1/authenticate" -Body $parameters
  
# POST method 
$token = Invoke-RestMethod -Method 'POST' "$($baseUrl)api/v1/authenticate" -Body $body -Headers $headers  

$authHeader = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $username,$token)))  

$products = Invoke-RestMethod -Method Get -Uri "$($baseUrl)api/v1/products" -Headers @{Authorization="Basic $authHeader"}