---
updatedAt: 2026-10-08T11:15:48.000Z
agentTools:
  siteIndex: https://docs.here.com/llms.txt
  projectIndex: https://docs.here.com/location-reasoning/llms.txt
---

# Connect and authenticate

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](https://docs.here.com/location-reasoning/docs/hlrgetting-started).

## 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](https://docs.here.com/location-reasoning/docs/hlrgetting-started) to generate the key, and [Using OAuth 2.1 in the HERE Platform](https://docs.here.com/identity-and-access-management/docs/how-to-authorize-with-oauth-21) to register the application and JWK on the HERE platform.

**OAuth 2.0**

[Register an application](https://docs.here.com/identity-and-access-management/docs/manage-apps) 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:

```text
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](https://docs.here.com/location-reasoning/docs/hlrgetting-started).

### 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.

```python
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`:

```text
Authorization: Bearer <HERE_ACCESS_TOKEN>
```

## Send requests to the MCP endpoint

Send all MCP requests to the HERE Location Reasoning endpoint:

```text
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.

```text
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.

| Method                      | Requires bearer token | Description                                             |
| --------------------------- | --------------------- | ------------------------------------------------------- |
| `initialize`                | No                    | Starts an MCP session and returns server information.   |
| `notifications/initialized` | No                    | Confirms that the client is ready after initialization. |
| `tools/list`                | No                    | 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

```bash
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`:

```json
{
  "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](https://docs.here.com/location-reasoning/docs/hlrexamples)**: Use ready-to-run framework integrations for LangChain, Strands Agents, PydanticAI, and more.
* **[HERE Location Reasoning tools reference](https://docs.here.com/location-reasoning/docs/hlrtools-reference)**: Review the complete list of available location tools.