When building integration with ODS, 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-to-ODS communication where an individual user is not interacting with ODS. Unattended integration uses service users, created by a Site Admin in ODS Admin.
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
Service users are used for unattended integration. A Site Admin can create service users for their site in the ODS Admin portal (see Site Service Users). Each service user only has access to a single site's data. Software vendors building integrations for customers must allow the customer to securely enter their own service user credentials.
Service users cannot be used to log in to Orica web applications or the API documentation (Swagger) page. To explore and test the API, log in to https://api.blastiq.com/v3/ with your own ODS Platform account.
There are two types of service users, and each uses a different OpenID Connect (OIDC) flow:
Client Credentials (Recommended)
Client Credentials uses the Client Credentials Grant Flow with a client ID and client secret. Use this for all new integrations.
The integration code retrieves an access token using the service user's Client ID and Client Secret from ODS Admin. Do not send a scope with the request. Access is controlled by the permissions assigned to the service user in ODS Admin.
Example C# code using IdentityModel
// Requires the IdentityModel NuGet package
using IdentityModel.Client;
var client = new HttpClient();
var disco = await client.GetDiscoveryDocumentAsync("https://www.odsplatform.com/identity");
if (disco.IsError)
{
Console.WriteLine(disco.Error);
return;
}
var tokenResponse = await client.RequestClientCredentialsTokenAsync(new ClientCredentialsTokenRequest
{
Address = disco.TokenEndpoint,
ClientId = "Your Client ID from ODS Admin",
ClientSecret = "Your Client Secret from ODS Admin"
});
if (tokenResponse.IsError)
{
Console.WriteLine(tokenResponse.Error);
return;
}
var accessToken = tokenResponse.AccessToken;Other language examples
Auth0 provides an overview of this flow and examples in several languages:
Authentication and authorization flow
Note: the Auth0 examples include an audience parameter. Do not send this parameter to BlastIQ.
Postman example
Make a POST to the URL below, formatted as application/x-www-form-urlencoded, with the following variables in the body:
- url: https://www.odsplatform.com/identity/connect/token
- grant_type: client_credentials
- client_id: the Client ID from ODS Admin (ends in @client.odsplatform.com)
- client_secret: the Client Secret from ODS Admin
The Client ID and Client Secret can also be sent as a Basic authorisation header instead of in the body.
Unused parameters
- scope: do not send this parameter
- username and password: do not send these parameters
The response has the content type application/json and includes the access token in the body. The Client Credentials flow does not return a refresh token. When the access token expires, request a new one using the same Client ID and Client Secret.
Resource Owner (Legacy)
Resource Owner uses the Resource Owner Password Grant Flow with a username and password. Supported for existing integrations.
For help choosing a type, see Understanding Service User Types in ODS Admin.
We recommend retrieving tokens using a client library. Suitable client libraries are available in most programming languages. With some libraries, you only need to specify the ODS identity server, while others need slightly more configuration.
Authentication type
oidc
Authority
https://www.odsplatform.com/identity
Discovery document
https://www.odsplatform.com/identity/.well-known/openid-configuration
Example c# code using IdentityModel.OidcClient2
var disco = await DiscoveryClient.GetAsync("https://www.odsplatform.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
Postman 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.odsplatform.com/identity/connect/token
- grant_type: password
- username: the Username from ODS Admin (ends in @service.blastiq.io)
- password: the Password from ODS Admin
- 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
The response will have the content type application/json and include the token and other necessary parameters in the body:
If you want to decode the token and look at what it contains, you can examine it using https://jwt.io/