Using an Opaque Access Token

Opaque access tokens are tokens in a proprietary format that you cannot access and typically contain some identifier to information in a server's persistent storage. The opaque token is the authentication and authorization mechanism to access the Typeahead API.

Step 1. Encode the credential and secret

Using the credential and secret provided to you, base64 encode the two values in the below format. Once the values have been base64 encoded, the output can be securely stored and retrieved for all requests as that value will not change.

Sample base64 Encoding:

#! /bin/bash
# Sample way to base64 encode the credential and secret
# Replace the $CREDENTIAL and $SECRET with the values provided to you.
echo -n '$CREDENTIAL:$SECRET' | base64
# Example output from above; this is not a real value.
# Ui55NmJhM2EtNmQwNC00M3klLTg5ZDQtYzNiN2ZiMDMxNGM2OmRrc04jTk59blV2QGFiMm1+YSoabnFPdWtCQUBUZHUA

Step 2. Get the Opaque Token

Get the opaque token by making an opaque token request.

Opaque Token Request Details:

Method: POST
Path: /identity/oauth2/v3/token
 'Authorization: Basic $BASE64_ENCODED_CREDENTIAL_SECRET' # This is the value from the previous step
 'Accept: application/json'
 'Trace-Id: $UUID' # Example: eb837c3a-1ef6-11eb-adc1-1442ac210033

Sample Opaque Token Request/Response:

#! /bin/bash
# Sample Request:
curl -L -X POST "" \
  -H "Authorization: Basic $BASE64_ENCODED_CREDENTIAL_SECRET" \
  -H 'Accept: application/json' \
  -H "Host:" \
  -H 'Trace-Id: eb837c3a-1ef6-11eb-adc1-1442ac210033'
# Sample Response:
# {"access_token":"<OPAQUE_TOKEN_HERE>","token_type":"bearer","expires_in":1799,"scope":"<LIST_OF_SCOPES_HERE>"}

Step 3. Use the Opaque Token

The opaque token retrieved from the previous step will be used for all requests to the API, for as long as the token is not expired. A new opaque token is not needed for every API request. The opaque token is valid for 30 minutes, so a new opaque token will have to be retrieved before it expires.

#! /bin/bash

# Sample Request:
curl --location -X GET ",MO&language=en-US&region_type=CITY&region_type=NEIGHBORHOOD" \
-H 'Authorization: Bearer $OPAQUE_TOKEN' \
-H 'Accept: application/json' \
-H 'Host:' \
-H 'Trace-Id: eb837c3a-1ef6-11eb-adc1-1442ac210033'

# Sample Response:
# The response is not important for this example. This is just one api request that utilizes the opaque token.
Did you find this page helpful?
How can we improve this content?
Thank you for helping us improve Developer Hub!