OAuth 2.0 tokens
Last UpdatedAug 28, 20255 minute read
Identity and Access ManagementDeveloper guideActive
HERE allows you to create API keys or OAuth 2.0 bearer access tokens for authorization.
Note
Trusted domains aren't enforced with 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 used for up to 24 hours by your app. If you try to call HERE APIs with an outdated token, you get a 401 Unauthorized error.
The API requests access tokens and has a fixed limit to protect service health. The limit per appId sets to a default of 25,000 requests per 15 minutes enforced at 1666 requests per minute across all calls to Here Account APIs.
Prerequisites
HERE supports the following operating systems:
Windows 10
Linux (Ubuntu 18.04)
macOS Sierra or higher
The OLP CLI requires the Java Runtime Environment (JRE) version 1.8.0_91 or higher. If you used winget to install the OLP CLI, you likely already have an OpenJDK 17 image installed, in which case it's not necessary to separately install the JRE.
To obtain your OAuth 2.0 tokens:
Step 1 - Register your app and get credentials
Before you can use OAuth 2.0 tokens, you must register your app on the HERE platform and acquire your credentials.
Note
Your associated authentication credentials are specific to your app and do not inherit your user permissions or group memberships.
Register your app
In your local development environment, create a .here folder in your home directory.
For Mac/Linux users, this will be $HOME/.here
For Windows users, this will be C:\%HOMEPATH%\.here, if your home directory is on your C drive.
Sign in to the HERE platform.
Select the Access Manager from the launcher.
On the Apps tab, click Register new app and provide the requested information.
Click Register. The platform creates a new app with a unique app ID.
Get your credentials
On the Credentials tab, select OAuth 2.0 and then click Create credentials.
In the dialog box that opens, click Download to download your app's credentials.properties file.
This file contains your user ID, app ID (which is named here.client.id), OAuth 2.0 token endpoint URL, access key ID, and access key secret.
Note that once you click Close, you can no longer access your access key ID and access key secret.
Copy the credentials.properties file to the .here folder you created in the first step.
The credentials.properties file contains your platform credentials, which the OLP CLI and libraries use to manage access to the platform. You can also use the included OAuth 2.0 token credentials to make authenticated calls to various HERE REST APIs.
For more information on using the OLP CLI, see the Command Line Interface Developer Guide.
Step 2 - Install OLP CLI
Install the OLP CLI via your preferred method.
Installation options
Installation options
Step 3 - Get a token
After registering an app, you can use OAuth 2.0 tokens to authenticate requests. An app can use a maximum of two tokens.
You can use the OLP CLI to get a token. For more information, see the HERE OLP CLI - User Guide.
Warning
Keep your credentials private, and never share them between workstations and users, or in public repositories on sites like GitHub.
To get a token:
Sign in to the HERE platform.
Select Access Manager from the launcher.
Click Apps and select an app which you previously registered.
Select OAuth 2.0 from the Credentials tab.
Click Create credentials.
In the dialog box that opens, click Download to download the credentials.properties file. Note that once you click Close, you can no longer access your access key ID and access key secret.
To create a default profile and associate your credentials with it, run the following command:
olp credentials import default credentials.properties
To get a token, navigate to the directory that contains the OLP CLI JAR file and run the following command: olp api token get
olp api token get
If your credentials are properly configured, you'll see a returned token, as well as output similar to the following:
Token: eyJhbGciOiJSUzUxMiIsImN0eSI6IkpXVCIsImlzcyI6IkhFUkUiLCJhaWQiOiJtekxjYjFyTDhuc2t2RFFwQ0ZFRiIs
ImlhdCI6MTUyMTgwNjYyOCwiZXhwIjoxNTIxODkzMDI4LCJraWQiOiJqMSJ9.ZXlKaGJHY2lPaUprYVhJaUxDSmxibU1pT2lKQk
1qVTJRMEpETFVoVE5URXlJbjAuLmtGc0JMODJibEUxTHhCS1M3MEctcFEuZHhsb2psaklEQmdNVEdoMEFKMHAzUU9yeE9INXdhd
1hkWjVSLS1Kdkc3VFBoUkRWY3owcUFYZ0V2Y3kwOGpMdzBCR09sNjJfZ2pxeUNuLXhET3JtZV8xNUlkV0tJN2VxTUpZNTNJelRx
ZjhUSzdVVHlEUlJFVnBLRW5BN2FvR2MubFViMTNGYWdKMlVGZXVQZnZsVG44Y2JqTzdtbF9ncGpLamFUN0xmZFF0UQ.EPYB9Rdy
jCHFxrqpaEBWkPzhPmFrAPBKlkt8SQpcI0k71mH_vC6txh6Uv1NVQC4xYyWG7ueq5mb4mcQh1sCorcv15GwIH1R0v0NR_CRPh-M
DNSFtg8HNnWyC1ePsfUGpSqjucQW8RMdbsU03wDO50Pr3ctQI4BZrxiU4HW6tdQq9_TinizujACzE-LMZ6FlFAb6pPB8TDsFlY3
9OmBFXEanaPvZwE01dKjE1K_A_G1_TiJzWo4vwuNeD54HfmOf6hN1IE8-CCSKRoIFoIBiVNqqzyCybyovRlSCWzSaTNz4v9BD7N
2lDgEuBlpn3q0qTFppZzjEvzv3RicGrCC_tmB
Token Expires at: 2018-03-24T14:03:48.100Z
Step 4 - Use the token
After obtaining a token, you must code your app to retrieve an OAuth 2.0 token for each request to a HERE service. Start by including the token in the HTTP Authorization header of your REST requests as a bearer token:
Authorization: Bearer <token>
With your token, you can query HERE services with an API REST request as shown in the following example.
Sample REST Request
The following sample request uses a GET method to retrieve a list of parking facilities within 500 meters of a point in Berlin.
Sample Request
The URL https://parking-v2.cc.api.here.com/parking/facilities.json specifies the endpoint for retrieving parking facility data in JSON format.
The query parameters ?prox=51638,13.38244,500 indicate the geographic coordinates (latitude and longitude) and a radius (500 meters) for the search.
The -H "Authorization: Bearer {YOUR_TOKEN}" line adds an authorization header. In a real API call, {YOUR_TOKEN} would be replaced with a valid access token for authentication.
curl GET
https://parking-v2.cc.api.here.com/parking/facilities.json
?prox=52.51638,13.38244,500
-H "Authorization: Bearer {YOUR_TOKEN}"
Sample response
The response produces details for a parking facility.
The top-level object contains two properties:
hasMore A boolean indicating if there are more facilities available. In this example, the value is returned as false.
facilities An object that holds an array of facility details.
The facility object includes various parameters describing the restaurant, such as its operating hours, address, and contact information.
{
"hasMore":false,
"facilities":{
"facility":[
{
"open24x7":true,
"facilityDetails":{
"openingHours":{
"openNow": true,
"regularOpeningHours":[
{
"daymask":127,
"period":[
{
"from":"00:00:00",
"to":"24:00:00"
}
]
}
],
"annualOpenings":[
]
},
"driveMaxHeight":1.8,
"facilityType":{
"name":"Parking Facility",
"id":"1"
},
"facilityOperator":"APCOA GmbH",
"facilityLevels":2,
"facilityInfrastructures":{
"name":[
"handicappedparkingspaces",
"securitymanned",
"elevators",
"light"
]
},
"facilityAdministration":{
"name":[
"Monitored",
"Gate"
]
},
"facilityRestrictions":{
},
"paymentMethods":[
{
"name":"Cash - EUR",
"id":"CASH"
}
]
},
"facilityAvailability":{
"spacesTotal":173,
"available":true,
"pricing":{
"price":[
{
"priceGroup":0,
"amount":2.0,
"currency":"EUR",
"unit":30,
"daymask":127,
"minMinutes":0,
"maxMinutes":30,
"textRepresentation": [
{
"text": [
"First 30 minutes",
"Per 30 minutes",
"Every day"
],
"language": "en-US"
}
]
},
{
"priceGroup":1,
"amount":4.0,
"currency":"EUR",
"unit":60,
"daymask":127,
"minMinutes":31,
"maxMinutes":60,
"textRepresentation": [
{
"text": [
"Over 31 minutes",
"Max 1 hour",
"Per hour",
"Every day"
],
"language": "en-US"
}
]
},
{
"priceGroup":2,
"amount":38.0,
"currency":"EUR",
"unit":1440,
"daymask":127,
"minMinutes":61,
"maxMinutes":1440,
"textRepresentation": [
{
"text": [
"Over 1 hour and 1 minute",
"Max 24 hours",
"Per day",
"Every day"
],
"language": "en-US"
}
]
}
]
},
"lastUpdateTimestamp":"2016-06-06T06:50:31.000Z"
},
"address":{
"city":"Berlin",
"country":"DEU",
"region":"Berlin",
"street":"Unter den Linden",
"streetNumber":"77",
"postalCode":"10117"
},
"contacts":{
"phone":[
{
"value":"+4971130570305",
"label":"PHONE"
}
]
},
"distance":166,
"position":{
"latitude":52.51631,
"longitude":13.37999
},
"name":"Hotel Adlon",
"id":"276u33db-e63737ae997c4a1ab5a19c50a63af49e",
"lastUpdateTimestamp":"2016-05-31T01:04:46.015Z",
"timeZone":"Europe/Berlin"
},
{
---removed to shorten document
}
]
}
}
Next steps
For more information about authentication and authorization, see the Identity and Access Management Authentication v1.1 API Reference and the Identity and Access Management Authorization v1.1 API Reference.