Authentication for Data Shop product APIs

Introduction

This documentation is provided as a reference where the use of an open source OAuth2 client library for authentication is not available.

DataShop products accessible via API require a Json Web Token (JWT) as a bearer access token to authenticate every API request. You need to get a bearer token and then use it in the Authorization header of each API request to use the API to access the product data successfully. It is used by the API endpoint to confirm you have access to the product before providing product data. Most programming languages will have libraries with support for OAuth2 which can automate this process, but it is explained in detail on this page for reference and to help debug and test product API calls using interactive API-docs.

This documentation only applies to products where the shop has provided you a client_id and a client_secret in order to obtain access to to the product via an API. Downloadable products do not require API access or the use of these credentials.

Retrieving an access token

To obtain an access token, a request needs to be made to the CSIRO identity provider’s token endpoint following the Client Credentials flow, which is part of the commonly used OAuth 2.0 specification. The client credentials flow accepts your client_id and client_secret and provides you an Access Token. Your client_id and client_secret can be found in the order details page after purchasing a product. You can find your order history page via your account on the shop website or the 'order details' link provided in the order confirmation email.

Access Token Request

POST https://login.microsoftonline.com/a815c246-a01f-4d10-bc3e-eeb6a48ef48a/oauth2/v2.0/token

Parameters:

Name	In	Type	Required	Description
Content-Type	Header	String	Yes	Set to "application/x-www-form-urlencoded"
grant_type	Body	String	Yes	Set to "client_credentials"
client_id	Body	String	Yes	Set to the client_id that you have been supplied. (Can also be retrieved from the Data shop order history)
client_secret	Body	String	Yes	Set to the client_secret that you have been supplied. (Can also be retrieved from the Data shop order history)
scope	Body	String	Yes	Must be set to the client_id + "/.default" For example: 12345678-1234-1234-1234-1234567890AB/.default

Sample request:

POST https://login.microsoftonline.com/a815c246-a01f-4d10-bc3e-eeb6a48ef48a/oauth2/v2.0/token 
Content-Type: application/x-www-form-urlencoded 

grant_type=client_credentials
&client_id=12345678-1234-1234-1234-1234567890AB 
&client_secret=C1ient$ecr3t# 
&scope=12345678-1234-1234-1234-1234567890AB/.default

Access Token Responses

Access Token Response Status Codes

Status	Meaning	Description
200	OK	The request was valid and an access token has been returned: `{ "token_type": "Bearer", "expires_in": 3599, "ext_expires_in": 3599, "access_token": "eyJ0eXAiOiJKV1QiLCJub2…" }`
400	Bad Request	The request was invalid, such as a missing parameter.
401	Unauthorized	Invalid client credentials were supplied in the request.

Access Token Response Properties

A successful response (200 OK) will return the access_token as well as additional details that describe the token usage.

Property	Description

Property	Description
token_type	Outlines that the token is a bearer token (i.e. give access to the bearer of this token) and should be passed to the API through the Authorization header using the Bearer scheme.
expires_in	The amount of seconds until the access_token expires. Note: Once the access_token has expired it can no longer be used to call the API. When this occurs a new access_token must be requested from the identity provider.
ext_expires_in	This indicates the extended lifetime of the token. How long the access token is valid (in seconds) if the server isn't responding.
access_token	The value of the access_token. This is the value to be passed to the API in the Authorization header using the Bearer scheme.

Sample response:

Using the Access Token

When a 200 OK status is returned from the token endpoint, the access_token value from the response body can be extracted. This value is then set as the bearer token when calling the relevant DataShop Product API:

Examples

Postman Collection

This Postman Collection provides a pre-configured 'get token' request where only the the client_id, client_secret and scope parameters are required to test the request.

cURL example

Python example

Many of the Data Shop products provide Python examples using the popular requests library. The follow code snippet demonstrates how to use the requests-oauth2client library to perform Data Shop API requests.

The requests-oauth2client library can be installed using pip as follows:

Get Token example:

Next Steps

Please refer to the DataShop product documentation for details on how to call APIs for each product.