Authorisation flows for API integration

When building integration with BlastIQ, both Attended and Unattended authorisation is possible. 

You should use an attended integration flow where an individual user is interacting with BlastIQ. Do not distribute Service User credentials with desktop or other client applications where an individual user is interacting with BlastIQ.

Unattended integration is to be used for Server <-> BlastIQ communication where an individual user is not interacting with BlastIQ.

Attended API Integration

A user with access permissions to access a site's data in BlastIQ applications can also access the data using the API. This is useful for integrating interactive applications where a user can be asked to authenticate themselves.

A developer building an application with attended integration should contact BlastIQ Support for assistance by raising a ticket below.

Unattended API Integration

The Service User credentials are provided to a customer on request to be used for integrated applications accessing and updating data via the BlastIQ External API. Service User accounts will only have access to a single Site's data, software vendors building integrations for customers must facilitate the customer securely entering their own valid Service User credentials.

Implementing Unattended integration with the BlastIQ API requires authenticating using the OpenID Connect (OIDC) Resource Ownner Password Grant Flow. The integration code must retrieve a token using the customer's Service User credentials. We recommend you do this using a client library, suitable client libraries are available in most programming languages. Using some client libraries you may only need to specify the BlastIQ identity server (https://www.blastiq.com/identity/) and it will complete most of the process for you, others may require slightly more configuration.

Authentication type

oidc

Authority 

https://www.blastiq.com/identity

Discovery document

https://www.blastiq.com/identity/.well-known/openid-configuration

Example c# code using IdentityModel.OidcClient2

var disco = await DiscoveryClient.GetAsync("https://www.blastiq.com/identity"); 
if (disco.IsError)
{
Console.WriteLine(disco.Error);
return;
}
var tokenClient = new TokenClient(disco.TokenEndpoint, "Insert your Client ID provided by BlastIQ Support");

var tokenResponse = await tokenClient.RequestResourceOwnerPasswordAsync(username, password, scope: null);

if (tokenResponse.IsError)
{
Console.WriteLine(tokenResponse.Error);
return;
}
var accessToken = tokenResponse.AccessToken;
var refreshToken = tokenResponse.RefreshToken;

 Python

https://docs.authlib.org/en/latest/client/oauth2.html#oauth2session-for-password

Other language examples

Auth0 provides several examples of this flow in different languages

https://auth0.com/docs/api-auth/tutorials/password-grant#ask-for-a-token 

Postman Example

Postmann can be used to demonstrate the Resource Owner Password Grant flow.

Make a Post to the url formatted as application/x-www-form-urlencoded with the following variables in the Post body:

  • url: https://www.blastiq.com/identity/connect/token
  • grant_type: password
  • username: as obtained from BlastIQ Support
  • password: as obtained from BlastIQ Support
  • client_id: external.customer

Unused parameters

  • audience: do not send this parameter
  • scope: you should not need to send this parameter, however some client libraries require scope and you can use the scope "cosmos"
  • client_secret: do not send this parameter

credentials_post.jpg

encoding.jpg

The response will have the content type application/json and include the token and other necessary parameters in the body:
token_response.jpg

If you want to decode the token and look at what it contains, you can examine it using https://jwt.io/

blobid0.png

 

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request