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.

Note

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):
grant_type=client_credentials
 &scope=hrn:here:authorization::myrealm:project/myproject
 &oauth_consumer_key=access-key-id-1234
 &oauth_nonce=LIIpk4
 &oauth_signature_method=HMAC-SHA256
 &oauth_timestamp=1456945283
 &oauth_version=1.0

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):

POST
 &https%3A%2F%2Faccount.api.here.com%2Foauth2%2Ftoken
 &grant_type%3Dclient_credentials%26scope%3Dhrn:here:authorization::myrealm:project%2Fmyproject%26oauth_consumer_key%3Daccess-key-id-1234%26oauth_nonce%3DLIIpk4%26oauth_signature_method%3DHMAC-SHA256%26oauth_timestamp%3D1456945283%26oauth_version%3D1.0

Note

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 here.access.key.secret property.

Since HERE does not use the "token secret" field, the signing key is just the encoded consumer secret followed by an ampersand ("&"). For example:

NtxCeo4IE3XESAMPLEwY3348TVYPWAcB_-WaoeSAMPLEW-cowuEhn1Xg2cmhP5fqqqq83s0OwpaoNSAMPLE&

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:

URL

https://account.api.here.com/oauth2/token

HTTP Header

Content-Type: application/x-www-form-urlencoded
Authorization: OAuth
oauth_consumer_key="<Access Key>",
oauth_nonce="<Random string, uniquely generated for each request>",
oauth_signature="<Signature>",
oauth_signature_method="HMAC-SHA256",
oauth_timestamp="<Epoch seconds>",
oauth_version="1.0"

Request Body

The request body must contain:

grant_type=client_credentials

Note

The value for grant_type must always be client_credentials.

An optional scope can be added to the request body to request a project scoped access token

scope="hrn:here:authorization::myrealm:project/myproject"

Sample Request

POST /oauth2/token HTTP/1.1
Host: account.api.here.com
Authorization: OAuth
oauth_consumer_key="1tqA_sample1fLhs2z6_q1l",
oauth_signature_method="HMAC-SHA256",
oauth_timestamp="1512072698",
oauth_nonce="ZGAaMP",
oauth_version="1.0",
oauth_signature="Q0sample4lqICrx19%2F4ahaH%2Fi2O0NgqDUQJgti5U3Q%3D"
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
scope="hrn:here:authorization::myrealm:project/myproject"

Response

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.

Sample Response

{
    "access_token":"VE5URXlJbjAuLmE4S0l4eVpQVE1zbHRwcnQyZ1BSVGcuS3RHT2V...",
    "token_type":"bearer",
    "expires_in":86399,
    "scope":"hrn:here:authorization::myrealm:project/myproject"
}

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.

Note

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

GET /maptile/2.1/maptile/newest/normal.day/13/4400/2686/256/png8
Host: 1.base.maps.ls.hereapi.com
Authorization: Bearer eyJhbGceOyJSAMPLEiIsImN0eSISAMPLEt7VTFIllwIM0cKNCjN2WCCTqlwEEmk-t3gx1BpqUFoeBSAMPLEvhj8nl-RBGcyoljY...
Cache-Control: no-cache

results matching ""

    No results matching ""