Authentication for Data Shop product APIs
- Chris Sharman
- Chris Sharman
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 |
|---|---|
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.