Code an OAuth 2.0 token request
If you choose to use OAuth 2.0 token authentication, you will need to code your application to obtain OAuth 2.0 Token Credentials for each request to a HERE service. You may choose to write your own code to do this, use the available from HERE Java AAA SDK or utilize 3rd party libraries, many of which are listed on this OAuth site.
This topic provides information on how to generate correctly signed OAuth 2.0 bearer access tokens in order to make requests to HERE services. HERE provides REST APIs to obtain these secure access tokens that your application can use for up to 24 hours for the purpose of authenticating requests to the HERE platform. Create a new signature and request a new token when your old one expires.
Step 1. Register your application
Registering your application generates an access key ID and access key secret, which are required to obtain a token. If you have not already registered your application, do so before proceeding.
- If you are a the HERE platform user, get API credentials for your app as described in OAuth tokens.
- If you are a developer.here.com user, get API credentials for your app as described in OAuth tokens.
Step 2. Create a signature
Using your access key ID and access key secret, create a token signature. The HERE Authentication and Authorization API requires that you sign tokens using the signing process described in the OAuth Core 1.0 specification. You may choose to write your own code to do this, using either the HERE Java AAA SDK, or a third-party library, many of which are listed on this OAuth site.
You must create a new signature for each token request to the Authentication and Authorization API. Signatures can only be used once.
A) Create a signature base string
The first step in creating a signature is to create the signature base string. This string contains the parameters to use when generating the signature. To begin, make sure you have the parameters listed in the following table:
|Parameter ||Location ||Required? ||Description |
|grant_type ||body ||yes ||Always use "client_credentials". |
|scope ||body ||no ||The project HRN. |
|oauth_consumer_key ||header ||yes ||The access key ID for which you want to generate a token. In the credentials file that you download when you create an access key, the access key ID is the value in the |
here.access.key.id property. For more information see OAuth tokens (for the HERE platform) or OAuth tokens (for the developer portal).
|oauth_nonce ||header ||yes ||A unique string for this signature. The string cannot have been used in a previous signature. Each request to the Authentication and Authorization API must have a unique signature, and the value in this parameter is what is used to ensure the signature is unique. |
|oauth_signature_method ||header ||yes ||Always use "HMAC-SHA256". |
|oauth_timestamp ||header ||yes ||The number of seconds since the Unix epoch at the point the request is generated. The HERE platform rejects requests created too distant in the past or future. |
|oauth_version ||header ||yes ||Always use "1.0". Note that you must specify 1.0 because the signature itself follows the OAuth 1.0 specification even though the OAuth token conforms to the OAuth 2.0 specification. |
Combine the parameters into a single string as follows:
- URL encode every key and value.
- Sort the list of key-value pairs alphabetically by key.
- Concatenate each key/value pair, separating each with an ampersand character ("&"). The result is a signature base string that looks like this (line breaks are added for legibility):
B) Create the base string
Combine the HTTP method, base URL, and parameter string into a single string called the "base string". This is the string from which the signature is generated. The base string is in this format:
POST&https://account.api.here.com/oauth2/token&<URL encoded parameter string>
The base string consists of:
- The HTTP method in caps (POST) followed by an ampersand ("&").
- The URL of the HERE token service followed by an ampersand ("&").
- The URL-encoded parameter string.
For example (line breaks are added for legibility):
The URL-encoded base string should contain exactly two ampersands ("&").
C) Create the signing key
The signing key is the URL-encoded access key secret, followed by an ampersand ("&"). In the credentials file that you download when you create an access key, the access key secret is the value in the
Since HERE does not use the "token secret" field, the signing key is just the encoded consumer secret followed by an ampersand ("&"). For example:
D) Create the signature
Create the signature by passing the signature base string and signing key to the HMAC-SHA256 hashing algorithm and converting the result to a base64 string.
Step 3: Request a token
Once you have an access key and signature, you can request a token using one of the authentication APIs. For more information, see the API reference:
A typical request includes these elements:
oauth_nonce="<Random string, uniquely generated for each request>",
The request body must contain:
The value for
grant_type must always be
An optional scope can be added to the request body to request a project scoped access token
POST /oauth2/token HTTP/1.1
The response body contains:
|Parameter ||Description |
|access_token ||A token you can use to authenticate REST requests. |
|token_type ||The type of token issued by the Authentication and Authorization API. This value will always be "bearer" since the API issues bearer tokens. |
|expires_in ||The number of seconds until the token expires. Tokens expire 24 hours after they are issued. |
|scope ||The HRN of the project if a scoped token is requested. |
Using the access token
You have now successfully obtained an access bearer token to use in making REST requests to HERE APIs. Creating the signature for requesting a token is not always straightforward. In our SDKs, you can find examples of how to create and use the tokens.
This code assumes that the credentials.properties file is stored in the folder ~/.here/.
Using the HERE Java SDK, the creation of a token can be done with two lines of code:
HereAccessTokenProvider accessTokens = HereAccessTokenProvider.builder().build();
String accessToken = accessTokens.getAccessToken();
Include the token in the HTTP Authorization header of your REST requests as a bearer token:
Authorization: Bearer <token>
Sample REST Request
Authorization: Bearer eyJhbGceOyJSAMPLEiIsImN0eSISAMPLEt7VTFIllwIM0cKNCjN2WCCTqlwEEmk-t3gx1BpqUFoeBSAMPLEvhj8nl-RBGcyoljY...