OAuth tokens

Note

This topic describes how to use OAuth tokens on the HERE platform. For instructions on using tokens on the HERE developer portal, see OAuth tokens.

Token credentials conform to the OAuth 2.0 industry standard protocol for Bearer Access Tokens. HERE provides REST APIs to obtain these secure access tokens that may be used for up to 24 hours by your application for the purpose of authenticating requests to the HERE platform.

Note

The API used to request access tokens has a fixed limit to protect service health. The limit per appId is set to a default of 25,000 requests per 15 minutes. Additionally, every request to HERE services is verified against this API for validation and the result of the decision check is cached. Only decision cache misses will hit the HERE Account and count towards the quota.

To use OAuth 2.0 tokens,

Step 1: Register your application and get credentials

Note

Many of HERE's SDKs and tools, such as the CLI, manage the fetching and usage of the token for the user. In most cases you can skip steps 2 and 3.

To use OAuth 2.0 tokens, you must register your app on the HERE platform. To register your app, follow these steps:

  1. In your local development environment, create a .here folder in your home directory.
    • For Mac/Linux users, this would be $HOME/.here
    • For Windows users, this would be C:\%HOMEPATH%\.here (if your home directory is on your C drive)
  2. Sign in to the HERE platform.
  3. Open the Access Manager from the Launcher.
  4. On the Apps tab, click Register new app and provide the requested information.
  5. Click Register. The platform creates a new app with a unique app ID.
  6. On the Credentials tab, select OAuth 2.0 and then click Create credentials.
  7. In the dialog box that opens, click Download to save your access key ID and secret. This information, in addition to your user ID, app ID (named here.client.id) and OAuth 2.0 token endpoint URL are created in a file named credentials.properties Once you click Close, you can no longer access your access key ID and access key secret.

  8. Copy the credentials.properties file to the .here folder you created in the first step.

    The credentials.properties file contains your platform credentials. The platform CLI tool and libraries access this file to manage access to the platform. You can also use these OAuth 2.0 Token credentials to make authenticated calls to REST APIs such as those provided by HERE location services.

    For more on using the platform CLI information, see the Command Line Interface Developer Guide.

Note

Your application and associated authentication credentials are specific to your app and don't inherit your user permissions or group memberships.

Step 2: Get a token

Now that your app is registered you can get OAuth 2.0 tokens to authenticate requests. You will need to code your application to get an OAuth 2.0 token for each request to a HERE service.

Note

For security reasons, HERE access tokens have a limited lifetime. If you try to call HERE APIs with an outdated token, you get a 401 Unauthorized error.

There are multiple ways to get a token:

You can test the process of getting a token using Postman. For more information, see Test with Postman.

Get a token with the CLI

The platform CLI allows you to access platform services from the command line. To get a token using the CLI, use the api token get command.

olp api token get

This returns an OAuth 2.0 token that allows safe and secure communication with the HERE platform.

The api token get command has additional parameters that you may find useful. For more information about additional parameters, see the CLI Guide.

For example, the following command gets an access token you can use to call HERE APIs.

olp api token get --json

Here's an example of what the above command would return:

{
    "accessToken": "eyJhbGciOiJSUz...omKF5Mg-sBjryw",
    "expiresAt": "2019-02-19T16:17:26.388Z"
}

Get a token with the SDK or an API

To use the AAA Java SDK or an authentication API to get a token, see Code an OAuth 2.0 token request.

Step 3: Use the token

Having followed one of the above methods, you have now successfully obtained a token to use in making REST requests to HERE APIs.

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 ""