Versions Compared

Old Version 3

changes.mady.by.user Chris Sharman

Saved on

compared with

New Version 4

changes.mady.by.user Grant Ryan

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Excerpt

Introduction

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

AgDataShop 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.

Note

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

Code Block
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 AgData 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 AgData 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:

Code Block
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:

Code Block
 { 
    "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:

Code Block
200 OK 

{ 
    "token_type": "Bearer", 
    "expires_in": 3599, 
    "ext_expires_in": 3599, 
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJ...NOiYYE910ABO_A" 
} 

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 AgDataShop relevant DataShop Product API:

Code Block
GET /product_api_call/ 
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ...NOiYYE910ABO_A 

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

Code Block
curl --request POST 'https://login.microsoftonline.com/a815c246-a01f-4d10-bc3e-eeb6a48ef48a/oauth2/v2.0/token'  --form 'client_id="<ENTER CLIENT ID HERE>"' --form 'client_secret="<ENTER CLIENT SECRET HERE>"' --form 'scope="<ENTER CLIENT ID HERE>/.default"' --form 'grant_type="client_credentials"'

Python example

Many of the AgData 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 AgData Data Shop API requests.

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

...

Code Block
from requests_oauth2client import *
import requests

CLIENT_ID = '<ENTER CLIENT ID HERE>'
CLIENT_SECRET = '<ENTER CLIENT SECRET HERE>'

oauth2client = OAuth2Client('https://login.microsoftonline.com/a815c246-a01f-4d10-bc3e-eeb6a48ef48a/oauth2/v2.0/token', (CLIENT_ID, CLIENT_SECRET))
session = requests.Session()
session.auth = OAuth2ClientCredentialsAuth(oauth2client, scope=f'{CLIENT_ID}/.default')

# The session object can be used to make AgData Shop product API calls.
#response = session.get('<product api request>')
#e.g. if the product is Senaps based:
response = session.get('https://senaps.io/api/sensor/v2/')
print(f"Successful connection to Senaps for user {response.json()['_embedded']['user'][0]['id']}")


#This won't be needed in your code - it displays the token for API Docs use.
token = session.auth.client.client_credentials(**session.auth.token_kwargs).access_token
print(f"Token:\n{token}")

Next Steps

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