HERE Maps Authentication: API Key & OAuth 2.0 Guide (2026)

Authentication overview

HERE Maps offers various authentication mechanisms to secure access to its mapping and geospatial APIs. The choice of authentication method depends on the application's architecture, security requirements, and the type of client accessing the services. The primary methods available are API Keys and OAuth 2.0, each designed to address different use cases and security considerations. Proper authentication ensures that only authorized applications and users can consume HERE Maps services, preventing unauthorized usage and managing API consumption effectively.

Developers typically manage their credentials through the HERE Developer Portal, where they can generate, configure, and revoke API keys or set up OAuth 2.0 applications. Adhering to security best practices, such as restricting API key usage and securely storing credentials, is crucial for maintaining the integrity and security of applications built with HERE Maps APIs.

Supported authentication methods

HERE Maps supports two main authentication methods: API Keys and OAuth 2.0. Each method serves distinct purposes and offers varying levels of security and flexibility.

API Key Authentication

API Keys are unique identifiers assigned to a project or application. When using an API Key, it is typically passed as a query parameter (apiKey) in the request URL or as an Authorization header. While simpler to implement, API Keys offer less granular control than OAuth 2.0. Their security heavily relies on proper management, such as restricting access based on HTTP referrers or IP addresses to prevent unauthorized use. HERE Maps API documentation details how to include API keys in requests.

OAuth 2.0 Authentication

OAuth 2.0 is an authorization framework that enables an application to obtain limited access to a user's protected resources without exposing the user's credentials. HERE Maps supports common OAuth 2.0 grant types:

• Client Credentials Grant: Used for server-to-server authentication where the application itself is authorized, rather than an end-user. The client exchanges its client ID and client secret for an access token. This is suitable for backend services that need to access HERE Maps APIs directly without user involvement.
• Authorization Code Grant: Designed for confidential clients (like web applications) where an end-user grants permission. The flow involves redirecting the user to HERE's authorization server, where they log in and consent. The application then receives an authorization code, which it exchanges for an access token. This method is more secure for user-facing applications because the client secret is never exposed to the user agent.

OAuth 2.0 tokens typically have a limited lifespan and require periodic refresh, adding another layer of security by reducing the window of opportunity for token misuse if compromised. More information on OAuth 2.0 can be found in the official OAuth 2.0 specification.

Getting your credentials

To access HERE Maps APIs, you need to obtain credentials from the HERE Developer Portal. The process typically involves creating an account and setting up a project.

API Key Setup

1. Create a HERE Developer Account: If you don't have one, register on the HERE Developer Portal.
2. Create a Project: Navigate to the 'Projects' section and create a new project. This project will logically group your applications and API keys.
3. Generate an API Key: Within your project, you can generate new API keys. Each key is unique to your project.
4. Configure Restrictions (Recommended): For enhanced security, configure your API key with restrictions. You can specify allowed HTTP referrers (for web applications) or IP addresses (for server-side applications) that are permitted to use the key. This prevents unauthorized usage if your key is exposed.

OAuth 2.0 Setup

1. Create a HERE Developer Account and Project: Similar to API Key setup, start by creating an account and a project.
2. Register an OAuth 2.0 Application: Within your project, register a new OAuth 2.0 application. During this process, you will be assigned a Client ID and a Client Secret.
3. Configure Redirect URIs (for Authorization Code Grant): If using the Authorization Code grant, you must specify the valid redirect URIs that the HERE authorization server can return to after user authentication. These must match the URIs in your application exactly.
4. Securely Store Credentials: Your Client ID and Client Secret are sensitive. Store them securely, ideally in environment variables or a secrets management service, and never embed them directly in client-side code.

Authenticated request example

This example demonstrates how to make an authenticated request to the HERE Geocoding & Search API using an API Key. For OAuth 2.0, the process involves obtaining an access token first and then including it in the Authorization header.

API Key Example (JavaScript)

This JavaScript example uses the fetch API to make a request to the Geocoding API. Replace YOUR_HERE_API_KEY with your actual API key and adjust the query as needed.

const apiKey = 'YOUR_HERE_API_KEY';
const query = '200 S Mathilda Ave, Sunnyvale, CA';
const url = `https://geocode.search.hereapi.com/v1/geocode?q=${encodeURIComponent(query)}&apiKey=${apiKey}`;

fetch(url)
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log('Geocoding results:', data);
  })
  .catch(error => {
    console.error('Error during geocoding request:', error);
  });

OAuth 2.0 Client Credentials Example (Python)

This Python example demonstrates how to obtain an access token using the Client Credentials grant and then use it to make an authenticated request. This method is suitable for server-side applications.

import requests
import os

# --- OAuth 2.0 Token Acquisition ---
client_id = os.environ.get('HERE_CLIENT_ID')
client_secret = os.environ.get('HERE_CLIENT_SECRET')
token_url = 'https://account.api.here.com/oauth2/token'

try:
    token_response = requests.post(
        token_url,
        data={'grant_type': 'client_credentials'},
        auth=(client_id, client_secret)
    )
    token_response.raise_for_status() # Raise an exception for HTTP errors
    access_token = token_response.json()['access_token']
    print(f"Access Token obtained: {access_token[:10]}...")

    # --- Authenticated API Request ---
    geocode_url = 'https://geocode.search.hereapi.com/v1/geocode'
    query = 'Eiffel Tower, Paris'

    headers = {
        'Authorization': f'Bearer {access_token}'
    }
    params = {
        'q': query
    }

    geocode_response = requests.get(geocode_url, headers=headers, params=params)
    geocode_response.raise_for_status()
    print("Geocoding results:", geocode_response.json())

except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")
    if hasattr(e, 'response') and e.response is not None:
        print("Response content:", e.response.text)

Security best practices

Implementing strong security practices is essential for protecting your applications and preventing unauthorized access to HERE Maps services. Adhere to these guidelines when handling HERE Maps credentials:

• Never Expose API Keys in Client-Side Code: Directly embedding API keys in public client-side JavaScript or mobile app binaries makes them easily discoverable. For web applications, consider using a proxy server to append the API key to requests, or use referrer restrictions. For mobile apps, ensure keys are not hardcoded but managed via secure configuration or backend services.
• Use IP Address and HTTP Referrer Restrictions: Whenever possible, configure your API keys with restrictions. Limit API key usage to specific IP addresses (for server-side applications) or HTTP referrers (for web applications). This significantly reduces the risk of unauthorized use even if a key is compromised.
• Store Credentials Securely: API keys, OAuth client IDs, and client secrets should be stored in secure locations. For server-side applications, use environment variables, dedicated secrets management services (e.g., AWS Secrets Manager, Azure Key Vault, Google Secret Manager), or secure configuration files, rather than hardcoding them directly in your source code.
• Rotate API Keys and OAuth Tokens Periodically: Regularly rotate your API keys and refresh OAuth access tokens. This practice minimizes the window of vulnerability if a credential is ever compromised. OAuth 2.0 access tokens are inherently short-lived, but client secrets should also be rotated.
• Implement Least Privilege: Grant only the necessary permissions to your API keys or OAuth applications. If a specific key only needs access to the Geocoding API, ensure it doesn't have permissions for other services.
• Monitor API Usage: Regularly review your API usage logs in the HERE Developer Portal. Unusual spikes or patterns in usage could indicate unauthorized activity or a compromised key.
• Use OAuth 2.0 for User-Facing Applications: For applications that involve end-users and require access to user-specific data or delegated authorization, always prefer OAuth 2.0 (specifically the Authorization Code grant) over API keys. This provides a more secure and robust authorization flow.
• Validate and Sanitize Inputs: Ensure all inputs to your API calls are properly validated and sanitized to prevent injection attacks or other vulnerabilities that could indirectly lead to credential exposure or misuse.