Connect with OAuth credentials
This guide covers credential-based token authentication, then starts an MCP session, discovers tools, and calls a tool. It supports two authentication flows: OAuth 2.1 (private_key_jwt), the recommended flow, or OAuth 2.0 (HMAC-SHA256 signed credentials). To connect from an MCP client instead, use the interactive OAuth 2.1 flow described in Get started with HERE Location Reasoning.
Follow the MCP session lifecycle in this order:
initializecreates an MCP session and returns server capabilities and theMcp-Session-Idheader.notifications/initializedtells the server that the client is ready for normal operations.tools/listreturns the available tools and their schemas.tools/callruns a tool request. A valid bearer token is required forinitialize,tools/list, andtools/call.
Before you begin
Gather the credentials for the flow you plan to use.
OAuth 2.1 (recommended)
You need an APP ID (your OAuth client_id), a public key registered as a JWK with its Key ID, and the matching private key kept in your own environment.
To set these up, follow Step 1 of Authenticate a custom application with M2M credentials to generate the key, and Using OAuth 2.1 in the HERE Platform to register the application and JWK on the HERE platform.
OAuth 2.0
Register an application on the HERE platform. On the app page, go to the OAuth 2.0 section of the Credentials tab and create credentials. Store the Access Key ID and Access Key Secret it generates.
Create an access token
Both flows exchange your credentials for a short-lived access token at the same token endpoint:
https://account.api.here.com/oauth2/tokenThe access token is short-lived. Create a new token when the current token expires.
Create an OAuth 2.1 access token
HERE Location Reasoning uses HERE Account OAuth 2.1 tokens for authentication. Sign a short-lived JWT client assertion with your private key, then exchange it for an access token at the token endpoint.
For runnable code that signs the assertion and exchanges it for a token, see Step 2 of Authenticate a custom application with M2M credentials.
Create an OAuth 2.0 access token
Sign a request with your Access Key Secret by using HMAC-SHA256, then exchange the signed request for an access token.
import base64
import hashlib
import hmac
import time
import urllib.parse
import uuid
import httpx
TOKEN_URL = "https://account.api.here.com/oauth2/token"
KEY_ID = "<YOUR_ACCESS_KEY_ID>"
KEY_SECRET = "<YOUR_ACCESS_KEY_SECRET>"
RESOURCE = "https://hlr.here.ai/mcp"
def get_here_token() -> str:
"""Create a HERE OAuth 2.0 token with HMAC-SHA256 signed credentials."""
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
params = sorted([
("grant_type", "client_credentials"),
("resource", RESOURCE),
("oauth_consumer_key", KEY_ID),
("oauth_nonce", nonce),
("oauth_signature_method", "HMAC-SHA256"),
("oauth_timestamp", timestamp),
("oauth_version", "1.0"),
])
encoded_params = urllib.parse.urlencode(params, quote_via=urllib.parse.quote)
signature_base = "&".join([
"POST",
urllib.parse.quote(TOKEN_URL, safe=""),
urllib.parse.quote(encoded_params, safe=""),
])
signing_key = urllib.parse.quote(KEY_SECRET, safe="") + "&"
signature = base64.b64encode(
hmac.new(
signing_key.encode(),
signature_base.encode(),
hashlib.sha256,
).digest()
).decode()
authorization = (
f'OAuth realm="",'
f'oauth_consumer_key="{KEY_ID}",'
f'oauth_nonce="{nonce}",'
f'oauth_signature="{urllib.parse.quote(signature, safe="")}",'
f'oauth_signature_method="HMAC-SHA256",'
f'oauth_timestamp="{timestamp}",'
f'oauth_version="1.0"'
)
response = httpx.post(
TOKEN_URL,
content=urllib.parse.urlencode(
[("grant_type", "client_credentials"), ("resource", RESOURCE)],
quote_via=urllib.parse.quote,
).encode(),
headers={
"Content-Type": "application/x-www-form-urlencoded",
"Authorization": authorization,
},
timeout=30,
)
response.raise_for_status()
return response.json()["access_token"]Add the token to a request
Send the access token as a bearer token with each authenticated request:
Authorization: Bearer <HERE_ACCESS_TOKEN>Send requests to the MCP endpoint
Send all MCP requests to the HERE Location Reasoning endpoint:
https://hlr.here.ai/mcpAll requests must include:
- HTTP method:
POST Content-Typeheader:application/json- Request body: a JSON-RPC 2.0 payload
Start and use an MCP session
MCP uses a stateful JSON-RPC 2.0 interface. Start a session, save its session ID, and include that ID in every later request in the session.
1. Initialize the session
Send an initialize request. A successful response includes the Mcp-Session-Id header.
Mcp-Session-Id: <value-from-initialize-response>Save this value. Include it in every request after initialize; otherwise, requests can fail or route to a different session.
2. Notify HERE Location Reasoning that the client is ready
Send notifications/initialized after initialization. This notification does not return a response body.
3. List available tools
Send tools/list to retrieve available tools and their schemas.
4. Call a tool
Send tools/call with the session ID and a valid bearer token.
Authentication requirements
A bearer token is required for initialize, tools/list, and tools/call.
| Method | Requires bearer token | Description |
|---|---|---|
initialize | Yes | Starts an MCP session and returns server information. |
notifications/initialized | No | Confirms that the client is ready after initialization. |
tools/list | Yes | Lists available tools and their schemas. |
resources/list | No | Lists available MCP resources. |
resources/read | No | Reads an MCP resource by URI. |
tools/call | Yes | Runs a location tool. |
Run a complete session with cURL
HERE_LOCATION_REASONING_URL="https://hlr.here.ai/mcp"
TOKEN="<YOUR_HERE_ACCESS_TOKEN>"
# 1. Initialize the session. Save Mcp-Session-Id from the response headers.
curl -s -D - -X POST "$HERE_LOCATION_REASONING_URL" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-03-26",
"capabilities": {},
"clientInfo": {"name": "curl", "version": "1.0"}
}
}'
SESSION_ID="<from-response-header>"
# 2. Tell the server that the client is ready.
curl -s -X POST "$HERE_LOCATION_REASONING_URL" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-H "Mcp-Session-Id: $SESSION_ID" \
-d '{
"jsonrpc": "2.0",
"method": "notifications/initialized",
"params": {}
}'
# 3. List the tools available in this session.
curl -s -X POST "$HERE_LOCATION_REASONING_URL" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-H "Mcp-Session-Id: $SESSION_ID" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list",
"params": {}
}'
# 4. Call a tool. This request requires a bearer token.
curl -s -X POST "$HERE_LOCATION_REASONING_URL" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-H "Mcp-Session-Id: $SESSION_ID" \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "hlr___geocode",
"arguments": {"q": "Invalidenstrasse 116, Berlin, Germany"}
}
}'Troubleshoot connection and authentication errors
HTTP 401: Unauthorized
This error occurs when:
- An
initialize,tools/list, ortools/callrequest does not include theAuthorizationheader. - The bearer token has expired.
- The token signature is invalid.
Create a new token by using your OAuth flow (2.1 or 2.0), then retry the request.
HTTP 403: Forbidden
This error occurs when the token is valid but the account is not authorized to use HERE Location Reasoning.
Contact your HERE account representative to verify your entitlements.
HTTP 429: Too Many Requests
This error occurs when the request rate exceeds the per-customer limit.
Stop sending requests and retry after a short delay. If you consistently receive this error, contact your HERE account representative to discuss rate limit adjustments.
JSON-RPC errors
Tool execution errors use a standard JSON-RPC error response, even when the HTTP status is 200:
{
"jsonrpc": "2.0",
"id": 3,
"error": {
"code": -32000,
"message": "validation failed: ..."
}
}These errors indicate a tool-parameter problem, such as invalid input or a missing required field, rather than an authentication problem.
Next steps
- For ready-to-run framework integrations for LangChain, Strands Agents, PydanticAI, and more, see HERE Location Reasoning integration examples.
- For the complete list of available location tools, see HERE Location Reasoning tools reference.
Updated 12 days ago