OAuth 2.0 authentication

Industry Data Exchange See Relevant Rules or Procedures (IDX Industry Data Exchange) APIs use OAuth 2.0 tokens to authenticate and authorise participant systems. An OAuth 2.0 access token is required for all IDX APIs and represents:

A registered OAuth client
A specific URM account
The Participant ID(s) and permissions assigned to the URM account

All IDX APIs are OAuth 2.0 enabled and are accessed through the AEMO API Gateway The gateway on AEMO’s side providing participant communication options, accessible over the internet or MarketNet. It uses resources and methods to push messages to Participants’ API Gateways . on MarketNet AEMO's private VPN for Registered Participants. A network of more than 300 registered participants in the National Electricity Market, including market generators, transmission network service providers, distribution network service providers, and market customers..

OAuth client

To access the IDX APIs, participants must create a Participant user account in User Rights Management (URM User Rights Management; see the Guide to URM on AEMO's website) and assign the required IDX entities. The URM account represents the OAuth client.

The URM account credentials (username and password) are used to authenticate when requesting an OAuth 2.0 access token from the OAuth 2.0 token endpoint. Specifically:

The username is used as the client_id.
The password is used as the client_secret.
Tokens are obtained using the OAuth 2.0 client_credentials grant type.
Authorisation is enforced using OAuth scopes.

OAuth scopes

An OAuth scope defines what a participant is allowed to access when calling IDX APIs. Each scope represents a URM entity, a Participant ID Registered participant identifier; A company can have more than one Participant ID., and permissions Create, Read, Update, and Delete (CRUD Create, read, update, and delete access rights.). Scopes determine which APIs and HTTP methods an OAuth access token can be used with. Only entities and permissions allocated to the user can be included in an OAuth scope.

When requesting an access token, participants can optionally include the scope parameter. If provided, the token is limited to the specified scopes only, resulting in a smaller, more efficient token and reduced security risk. If no scope is provided, the token includes all the scopes associated to the client_id..

AEMO Australian Energy Market Operator recommends to only request scoped tokens and include only the scopes required.

Multiple participant IDs

For a URM account associated with multiple Participant IDs, all matching scopes across all Participant IDs are returned. You cannot request a token for one Participant ID.

Example scopes

Scenario	Example	Result
No scope provided	A participant has PQD_BPQD and FCTRL_FCTRL No scope is provided when calling the OAuth token endpoint	Returns a token containing all the scopes associated with the client_id
Specific scopes provided	scope: PQD_BPQD FCTRL_FCTRL across two Participant IDs	Returns a token with matching scopes for all Participant IDs Scope: PQD_BPQD\|ParticipantID1\|RUCD FCTRL_FCTRL\|ParticipantID1\|RUCD PQD_BPQD\|ParticipantID2\|RUCD FCTRL_FCTRL\|ParticipantID2\|RUCD
Permission enforcement	scope: PQD_BPQD The Participant User has the PQD_BPQD entity assigned with read only permission	Returns a token with PQD_BPQD scope with read only permission. BPQD API POST requests are rejected. GET requests are allowed Scope: PQD_BPQD\|ParticipantID\|R

Scenario

Example

Result

No scope provided

A participant has PQD_BPQD and FCTRL_FCTRL

No scope is provided when calling the OAuth token endpoint

Returns a token containing all the scopes associated with the client_id

Specific scopes provided

scope: PQD_BPQD FCTRL_FCTRL across two Participant IDs

Returns a token with matching scopes for all Participant IDs

Permission enforcement

scope: PQD_BPQD

The Participant User has the PQD_BPQD entity assigned with read only permission

Returns a token with PQD_BPQD scope with read only permission. BPQD API POST requests are rejected. GET requests are allowed

Scope: PQD_BPQD|ParticipantID|R

Obtain an OAuth token

Obtain an OAuth 2.0 access token by calling the OAuth token endpoint POST /oauth/v1/token and providing the following details in the request.

Type	Property	Description
Request header	Content-Type: application/x-www-form-urlencoded	Specifies the request body content encoding
Body parameter	client_id	URM username
Body parameter	client_secret	URM password
Body parameter	grant_type	Must be client_credentials
Body parameter	scope	Optional. A space‑separated list of scopes. For help, see OAuth scopes

Example request:

POST /oauth/v1/token
Content-Type: application/x-www-form-urlencoded
client_id=idx_service_user
&client_secret=********
&grant_type=client_credentials
&scope=PQD Power Quality Data. Measurements of power supply characteristics exchanged between participants and AEMO._BPQD Basic Power Quality Data. A subset of power quality data consisting of voltage, current, and phase angle FCTRL_FCTRL

Example 200 response:

value:
	access_token: eyJhbGciOlJSYzI1NiIsInR5cCI6IkdXVCJ9...
	token_type: Bearer
	expires_in: 3600
	scope: PQD_BPQD|ParticipantID|RUCD FCTRL_FCTRL|ParticipantID|RUCD

You include the token in the Authorization header for an API Application Programming Interface; a set of clearly defined methods of communication between various software components. request.

Authorization: Bearer <access_token>