Skip to main content

How to generate an access token

The service uses OAuth 2.0 access tokens issued by AWS Cognito for authentication and authorisation. Access tokens have a validity of one hour.

Requirements

You need to have been issued credentials before following these instructions. Please see onboarding instructions for acquirers or onboarding instructions for suppliers to be issued credentials. You will be given a client ID and a client secret for a specific environment.

Environment

When you were issues credentials, you will have been told which environment they are for. Use the URL from the appropriate environment in the following steps.

OAuth Token URL

environment url
dev https://dev-gdx-data-share.auth.eu-west-2.amazoncognito.com/oauth2/token
demo https://demo-gdx-data-share.auth.eu-west-2.amazoncognito.com/oauth2/token
integration https://integration-life-events.auth.eu-west-2.amazoncognito.com/oauth2/token

Generate an access token

You may obtain an access token from Cognito using a client credentials grant with your client ID and client secret.

This can be done in two ways:

Form encoded credentials

Make an HTTP POST request to the OAuth Token URL endpoint with:

  • a Content-Type header with value application/x-www-form-urlencoded
  • a body (of format x-www-form-urlencoded) with key pairs:
    • a key of grant_type and value client_credentials
    • a key of client_id and value [Client ID]
    • a key of client_secret and value [Client Secret]

Bash script:

OAUTH_URL=[OAuth Token URL]
CLIENT_ID=[Client ID]
CLIENT_SECRET=[Client Secret]
JWT_TOKEN=$(curl --location --request POST "$OAUTH_URL" --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=client_credentials' --data-urlencode "client_id=$CLIENT_ID" --data-urlencode "client_secret=$CLIENT_SECRET" | jq -r .access_token)
echo $JWT_TOKEN

For example,

OAUTH_URL=https://dev-gdx-data-share.auth.eu-west-2.amazoncognito.com/oauth2/token
CLIENT_ID=aaaaaaaaaaaaaaaaaaaaaaaaaa
CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
JWT_TOKEN=$(curl --location --request POST "$OAUTH_URL" --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=client_credentials' --data-urlencode "client_id=$CLIENT_ID" --data-urlencode "client_secret=$CLIENT_SECRET" | jq -r .access_token)
echo $JWT_TOKEN

Basic Authorization

Make an HTTP POST request to the OAuth Token URL endpoint with:

  • a Content-Type header with value application/x-www-form-urlencoded
  • an Authorization header with value Basic: [Base64Encoded(clientId:clientSecret)]
  • a form (of format x-www-form-urlencoded) with a key of grant_type and value client_credentials

Bash script:

OAUTH_URL=[Oauth URL]
CLIENT_ID=[Client ID]
CLIENT_SECRET=[Client Secret]
JWT_TOKEN=$(curl --location --request POST "$OAUTH_URL" --header 'Content-Type: application/x-www-form-urlencoded' --header "Authorization: Basic $(echo -n $CLIENT_ID:$CLIENT_SECRET | base64)" --data-urlencode 'grant_type=client_credentials' | jq -r .access_token)
echo $JWT_TOKEN

For example,

OAUTH_URL=https://dev-gdx-data-share.auth.eu-west-2.amazoncognito.com/oauth2/token
CLIENT_ID=aaaaaaaaaaaaaaaaaaaaaaaaaa
CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
JWT_TOKEN=$(curl \
--http1.1 \
--location \
--request POST "$OAUTH_URL" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header "Authorization: Basic $(echo -n $CLIENT_ID:$CLIENT_SECRET | base64 -w 0)" \
--data-urlencode 'grant_type=client_credentials' | jq -r .access_token)
echo $JWT_TOKEN