Connect and authenticate

Beta availability
HERE Location Reasoning is currently available to beta participants. For information about joining the beta, visit HERE Location Reasoning.

Connect to HERE Location Reasoning by creating an OAuth access token, starting an MCP session, discovering available tools, and calling a tool.

HERE Location Reasoning supports two authentication flows. Use OAuth 2.1 (private_key_jwt), the recommended flow, or OAuth 2.0 (HMAC-SHA256 signed credentials).

Follow the MCP session lifecycle in this order:

1. initialize creates an MCP session and returns server capabilities and the Mcp-Session-Id header.
2. notifications/initialized tells the server that the client is ready for normal operations.
3. tools/list returns the available tools and their schemas.
4. tools/call runs a tool request. This method requires a valid bearer token.

For an end-to-end walkthrough, see Get started with HERE Location Reasoning.

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 Get started with HERE Location Reasoning 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/token

The access token is short-lived. Create a new token when the current token expires.

Create an OAuth 2.1 access token (recommended)

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 Get started with HERE Location Reasoning.

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 when you call a tool with tools/call:

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/mcp

All requests must include:

• HTTP method: POST
• Content-Type header: 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 only for tools/call. You can send an Authorization header with other methods, but it is not required.

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" \
  -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 "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 "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": "Berlin, Germany"}
    }
  }'

Troubleshoot connection and authentication errors

HTTP 401: Unauthorized

This error occurs when:

• A tools/call request does not include the Authorization header.
• 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

• HERE Location Reasoning integration examples: Use ready-to-run framework integrations for LangChain, Strands Agents, PydanticAI, and more.
• HERE Location Reasoning tools reference: Review the complete list of available location tools.