Acting for your users

A partner platform calls Advisor on behalf of its own users. Advisor does not know who they are and does not need to. Send a one-way hash of each user's identifier so usage can be counted per user, and pass on to your users what Advisor tells you about the law.

Before you begin

Steps

  1. Hash your user's identifier. Use a keyed hash, for example HMAC-SHA-256 with a secret only your platform holds, so the value cannot be reversed or matched to the user by anyone else.
  2. Send it on every request as X-LawAtlas-Subject. Advisor records up to 128 characters, as given, with the call. It never reads it for meaning.
  3. Show your users the status of the law. Pass on confirmed_with_frl_at, the compilation and the Federal Register link with any text you show. See Data currency and status.
  4. Keep the Hansard conditions if your platform shows Hansard: verbatim passages, the attribution and the official record link, and a label that your service is not the official record. See Hansard.

Python SDK

import hashlib, hmac, os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

def subject_for(user_id: str) -> str:
    secret = os.environ["SUBJECT_HASH_SECRET"].encode()
    return hmac.new(secret, user_id.encode(), hashlib.sha256).hexdigest()

async def ask(user_id: str, tool: str, arguments: dict):
    headers = {
        "Authorization": f"Bearer {os.environ['LAWATLAS_API_KEY']}",
        "X-LawAtlas-Subject": subject_for(user_id),
    }
    async with streamablehttp_client("https://advisor.lawatlas.ai/api/mcp-http/mcp", headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            return await session.call_tool(tool, arguments)

curl

curl -s https://advisor.lawatlas.ai/api/mcp-http/mcp \
  -H "Authorization: Bearer $LAWATLAS_API_KEY" \
  -H "X-LawAtlas-Subject: $SUBJECT_HASH" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"health","arguments":{}}}'

Warning: Never send a name, email address or other personal information in X-LawAtlas-Subject, and never a hash without a secret key: an unkeyed hash of an email address can be reversed by hashing a list of addresses.

Check it worked

Your calls succeed as before; the header changes nothing in the response.

What to do if it did not

The header is optional and never causes an error. If a call fails, see Troubleshooting.

Next steps