GraphHopper Authentication: API Key Security (2026)

Authentication overview

GraphHopper provides location-based services through a suite of APIs, including Routing, Matrix, Geocoding, Map Matching, and Route Optimization. Access to these services is controlled primarily through API key authentication. An API key serves as a unique identifier for your application, allowing GraphHopper to track usage, apply rate limits, and ensure authorized access to its resources. All communications with GraphHopper APIs are expected to occur over HTTPS to encrypt data in transit and protect API keys from interception.

The authentication model is straightforward: you obtain an API key from your GraphHopper account dashboard and include it with every API request. This method is common for web services that require simple, stateless authentication for public-facing APIs. For enhanced security, particularly in scenarios involving client-side applications, it is advisable to consider server-side proxies or other mechanisms to prevent direct exposure of API keys.

Supported authentication methods

GraphHopper's primary and recommended method for authenticating API requests is through a unique API key. This key is passed as a query parameter in your HTTP requests, allowing the GraphHopper server to verify your identity and permissions. While API keys offer simplicity, their security relies heavily on proper management and protection against unauthorized disclosure.

API Key

This method involves generating a unique string (the API key) from your GraphHopper account. You then append this key to your API request URLs as a query parameter. For instance, a typical request might look like https://graphhopper.com/api/1/route?point=...&key=YOUR_API_KEY. This approach is widely adopted due to its ease of implementation and compatibility across various programming languages and HTTP clients.

The security level of API keys is generally considered moderate. While effective for rate limiting and basic access control, API keys alone do not provide strong user authentication or granular permission control often found with OAuth 2.0 or other token-based systems. Therefore, developers are responsible for safeguarding their API keys to prevent misuse.

Getting your credentials

To obtain an API key for GraphHopper, you must first register for an account on the GraphHopper website. Upon successful registration, you can access your personal dashboard, which serves as the central hub for managing your API keys and monitoring usage.

1. Sign Up/Log In: Navigate to the GraphHopper homepage and either create a new account or log in to an existing one.
2. Access Dashboard: Once logged in, you will typically be redirected to your dashboard. Look for sections related to 'API Keys' or 'Developer Settings'.
3. Generate Key: Within the API Key management section, there should be an option to generate a new API key. GraphHopper allows you to create multiple keys, which can be useful for distinguishing between different applications or environments (e.g., development, staging, production).
4. Copy Key: After generation, your unique API key will be displayed. Copy this key immediately and store it securely. GraphHopper typically shows the key only once upon creation for security reasons. If you lose a key, you may need to generate a new one and revoke the old one.
5. Configure Applications: Integrate the copied API key into your application's configuration. Ensure that it is not hardcoded directly into public client-side code but rather loaded from environment variables or a secure configuration store, especially for server-side applications.

For more detailed instructions, refer to the GraphHopper documentation on authentication.

Authenticated request example

GraphHopper API requests are made over HTTPS, including the API key as a query parameter. Below are examples demonstrating how to make an authenticated request using cURL and JavaScript.

cURL Example

This cURL example demonstrates a basic request to the GraphHopper Routing API to calculate a route between two points, including the API key for authentication.

curl "https://graphhopper.com/api/1/route?point=51.131,12.414&point=48.224,14.263&vehicle=car&key=YOUR_API_KEY_HERE"

Replace YOUR_API_KEY_HERE with your actual GraphHopper API key. The point parameters define the start and end coordinates for the route, and vehicle specifies the mode of transport.

JavaScript Example (Client-side with caution)

While generally not recommended to expose API keys directly in client-side code, for demonstration or specific controlled environments, you might use fetch API. For production, consider a server-side proxy.

const apiKey = 'YOUR_API_KEY_HERE';
const startPoint = '51.131,12.414';
const endPoint = '48.224,14.263';
const vehicle = 'car';

const url = `https://graphhopper.com/api/1/route?point=${startPoint}&point=${endPoint}&vehicle=${vehicle}&key=${apiKey}`;

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

This JavaScript snippet constructs the URL with the API key and uses the fetch API to send the request. Remember to replace YOUR_API_KEY_HERE with your actual key.

Security best practices

Proper management of API keys is critical for securing your GraphHopper applications and preventing unauthorized access or abuse. Adhering to established security practices helps mitigate risks associated with credential exposure.

• Environment Variables: Store API keys in environment variables rather than hardcoding them directly into your application's source code. This practice prevents keys from being committed to version control systems and exposed in public repositories. For example, in a Node.js application, you might access the key via process.env.GRAPHOPPER_API_KEY.
• Server-Side Proxies: For client-side applications (e.g., web browsers, mobile apps), route all GraphHopper API requests through a secure server-side proxy. The proxy can add the API key to requests before forwarding them to GraphHopper, preventing the key from being exposed in client-side code or network traffic that could be intercepted. This method is a common security pattern for protecting credentials in distributed systems, as detailed in Google Maps API key best practices.
• Restrict Referrers/IP Addresses: If GraphHopper supports it, configure your API key to accept requests only from specific HTTP referrers (for web applications) or IP addresses (for server-side applications). This adds a layer of protection, as even if your key is compromised, it will only function from authorized sources. Consult the GraphHopper dashboard or documentation for options to restrict API key usage.
• HTTPS Enforcement: Always ensure that all API requests to GraphHopper are made over HTTPS. This encrypts the communication channel, protecting your API key and sensitive data from interception during transit. GraphHopper's API endpoints are designed to be accessed via HTTPS, making this a default expectation.
• Regular Key Rotation: Periodically rotate your API keys. This practice minimizes the window of opportunity for a compromised key to be exploited. If you suspect an API key has been exposed, revoke it immediately through your GraphHopper dashboard and generate a new one.
• Principle of Least Privilege: If GraphHopper offers granular permissions for API keys (e.g., read-only access, specific API endpoint access), configure your keys with the minimum necessary permissions required for your application's functionality. This limits the potential damage if a key is compromised.
• Monitoring and Alerts: Implement monitoring for unusual API usage patterns or spikes in requests that could indicate a compromised key. GraphHopper's dashboard provides usage statistics that can help identify anomalies. Consider setting up alerts if the platform supports them.