Skip to main content

ESL Authentication

This page outlines the sequence of requests required to gain a valid ESL access token, registering your machine user and orginaisation (EDUMIS) with the TEC APIs, and calling the TEC APIs with a bearer token.

Please review the following sequence diagram and refer to the notes below,

API Flow

Step 1: Generate an Access Token​

To generate an access token from the Education Sector Login (ESL), follow these steps:

  1. Using your terminal, command prompt, or tool of choice,

  2. Use the following curl command to request the token:

    curl --location 'https://security.education.govt.nz/oauth2/access_token' \
    --header 'Authorization: Basic <Base64(clientId:clientSecret)>' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode 'scope=https://web.prd.dxs.pub.tec.govt.nz' \
    --data-urlencode 'org_id=0123'

  3. This command sends a POST request to ESL, which will return a JSON response containing the access token. An example response might look like this:

    {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "token_type": "Bearer"
    }

  4. Extract the access_token from the response. This token will be used for subsequent API requests.

Step 2: Understanding the Access Token request​

This request gives the client application (your application) a token that indicates that it is authorised to use an ESL-protected application. Once the application acquires a token it can make requests to the ESL protected resources (i.e TEC Provider APIs). The token will continue to be valid for a period of time after it has been assigned, at which point the client application will have to re-authenticate (repeat the above access_token request).

The value for the Authorization: Basic header is a Base64-encoded string that consists of your clientId and clientSecret separated by a colon (:). The clientId is the "machine account name" provided by ESL, and the clientSecret is the password that has been set for that machine account. Here's how you can generate it:

  1. Combine your clientId and clientSecret into a single string separated by a colon. For example: 
    clientId:clientSecret
  2. Encode this string in Base64 format. You can use online tools, programming libraries, or command-line utilities to do this.

C# Example​

Here is a C# code snippet to generate the Base64-encoded credentials:

string encodedCredentials 
    = Convert.ToBase64String(Encoding.ASCII.GetBytes($"{clientId}:{clientSecret}"));

UNIX Example​

You can use the base64 command in a UNIX-like system:

echo -n 'clientId:clientSecret' | base64

Token Validity and Usage​

  • Token Validity: The access token is valid for twenty minutes from the time it is issued. After twenty minutes, a new access token will be required to continue making authenticated requests.
  • EID Values: The access token is valid for any combination of EID values the machine user has been granted access to within ESL. This means that you can use the same access token for different EID values within the validity period.

Step 3: Register your machine user and organisation​

Once you have successfully acquired a bearer token, you need to perform a one-time registration of each organisation you intend to perform delegated operations for, and which you have been granted access to by ESL. Within the TEC API suite, the organisation ID for which you are performing actions is represented as the EID header value for all requests.

Here is an example curl command to register an EID:

  1. Replace <access_token> with the token you received from ESL.

  2. Replace 0123 with the EDUMIS/Organisation ID of the organisation you are registering.

    curl --location --request POST 'https://api.prd.dxs.pub.tec.govt.nz/provider-submission-api/user/register' \
    --header 'Authorization: Bearer <access_token>' \
    --header 'EID: 0123'

Step 4: Use the Access Token to Call the API​

With the access token obtained and User/EID combination registered, you can now make authorized requests to the TEC API. Here's an example curl command to do so:

  1. Replace <access_token> with the token you received from ESL.

  2. Replace 0123 with the organization ID you used previously.

    curl --location 'https://api.prd.dxs.pub.tec.govt.nz/provider-submission-api/resource' \
    --header 'Authorization: Bearer <access_token>' \
    --header 'EID: 0123'

Example Requests​

Below are examples of how the requests might look in practice:

  1. Request Token:

    curl --location 'https://security.education.govt.nz/oauth2/access_token' \
    --header 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc...' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode 'scope=https://web.prd.dxs.pub.tec.govt.nz' \
    --data-urlencode 'org_id=0123'

  2. Response:

    {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "token_type": "Bearer"
    }

  3. Register the user and organisation:

    curl --location --request POST 'https://api.prd.dxs.pub.tec.govt.nz/provider-submission-api/user/register' \
    --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
    --header 'EID: 0123'

  4. Use Token in API Call:

    curl --location 'https://api.prd.dxs.pub.tec.govt.nz/provider-submission-api/resource' \
    --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
    --header 'EID: 0123'