JS API: OAuth Bearer Access Token Authorization instead of apikey

HERE Maps API for JavaScript 3.x: How to use OAuth Bearer access token instead of API key on the frontend

Problem

Customers sometimes want to avoid exposing a HERE apikey in a frontend Maps API for JavaScript application and instead use an OAuth Bearer access token in the HTTP Authorization header. The recommended and standard authentication method for HERE Maps API for JavaScript 3.x is still API key authentication, but Bearer token authorization can be attempted for some use cases by passing custom headers or by implementing a custom provider.

Symptoms / Triggers

You may need this article if you experience any of the following:

You do not want to expose a HERE apikey directly in frontend JavaScript code.
Your security policy requires using an OAuth 2.0 Bearer access token instead of API key authentication.
You want to initialize H.service.Platform with an Authorization: Bearer header.
Map tiles or platform services do not load after replacing apikey authentication with Bearer token authentication.
Some HERE services work with the Bearer token header, but other services still fail or require a custom request implementation.
You need to send the OAuth token manually for raster tiles, vector tiles, or a custom tile provider.

Quick Answer

For HERE Maps API for JavaScript 3.x, the recommended authentication method is still apikey. However, you can try OAuth Bearer token authorization by passing the headers property during H.service.Platform initialization.

Important: this approach may not work for all HERE services used by Maps API for JavaScript. Test your application carefully before deploying to production. If a specific service does not accept the global platform header, create a custom provider and send the Authorization: Bearer header manually in the request.

Step-by-step Solution

1. Use the standard API key method when possible

The standard and recommended authentication method for Maps API for JavaScript is apikey. If your application does not have a strict requirement to use OAuth Bearer tokens, use the documented API key initialization flow.

https://www.here.com/docs/bundle/maps-api-for-javascript-developer-guide/page/topics/quick-start.html

2. Generate or obtain an OAuth Bearer access token

If your application architecture requires OAuth authentication, obtain a valid OAuth access token using HERE Identity and Access Management. The token must be valid, not expired, and authorized for the HERE services your application calls.

https://docs.here.com/identity-and-access-management/docs/how-to-authorize-with-oauth-20

3. Pass the Authorization header during platform initialization

Define the headers property when creating the H.service.Platform instance. Use the Authorization header with the Bearer token value.

<br />// Step 1: initialize communication with the platformvar platform = new H.service.Platform({ apikey: "-", headers: { 'Authorization': 'Bearer your_bearer_token_here' }}`);<br />

Example: https://jsfiddle.net/qz26ytuh

Important: The above approach may not work for all services. Validate map rendering, routing, geocoding, tile loading, and any other HERE service calls used by your application before deploying to production.

4. If a service does not work with the global header, create a custom provider

For services such as custom raster or vector tile requests, you can implement a custom provider and set the Authorization header directly on the request.

<br />class CustomProvider extends H.map.provider.RemoteTileProvider { requestInternal(x, y, level, onSuccess, onError) { // Example raster tile request let url = `https://maps.hereapi.com/v3/base/mc/${level}/${x}/${y}/jpeg?lang=fr&lang2=en&style=explore.day&size=512`; const req = new XMLHttpRequest(); req.open("GET", url, true); req.setRequestHeader('Authorization', 'Bearer your_token_here'); req.responseType = "blob"; req.onload = (event) => { const blob = req.response; if (blob) { const img = new Image(); var imgUrl = URL.createObjectURL(blob); img.src = imgUrl; onSuccess(img); } }; req.onerror = onError; req.send(null); return { cancel: () => { req.abort(); // Request cancel } }; } providesRasters() { return true; }}`var cProvider = new CustomProvider({engineType: engineType});cProvider.setStyleInternal(new H.map.render.harp.Style({}));var rasterTileLayer = new H.map.layer.TileLayer(cProvider);var map = new H.Map( document.getElementById('map'), rasterTileLayer, { engineType: engineType, center: {lat: 50, lng: 5}, zoom: 4, pixelRatio: window.devicePixelRatio || 1 });<br />

5. Test all services used by your application

Before production deployment, test every HERE service endpoint used by the application. A Bearer token may work for one request path but fail for another. Verify at least map tile loading, base layer rendering, custom tile providers, routing, search, geocoding, reverse geocoding, and any additional platform services used by your application.

Examples

Basic Bearer token platform initialization: https://jsfiddle.net/qz26ytuh

Custom raster tile provider: https://jsfiddle.net/hudwyr3b

Custom vector tile provider: https://jsfiddle.net/doyLhvn2

Applies To

HERE Maps API for JavaScript 3.x
H.service.Platform
HERE Identity and Access Management OAuth tokens
Raster tile and vector tile requests using custom providers
* Browser-based frontend JavaScript applications

Documentation

OAuth tokens: https://docs.here.com/identity-and-access-management/docs/how-to-authorize-with-oauth-20

Maps API for JavaScript quick start: https://www.here.com/docs/bundle/maps-api-for-javascript-developer-guide/page/topics/quick-start.html

Searchable Tags / Keywords

OAuth Bearer token, Bearer access token, Authorization header, use token instead of apikey, hide API key frontend, avoid exposing API key, Maps API for JavaScript 3.x, HERE Maps JS, H.service.Platform headers, apikey recommended, OAuth token not working, map tiles not loading, custom tile provider, raster tile provider, vector tile provider, XMLHttpRequest Authorization header, HERE IAM token, frontend authentication, secure authorization, production deployment test, API key vs OAuth token