---
name: hemlo-keys
description: Create, scope, store, rotate and revoke Hemlo API keys (hsk_u_ personal, hsk_o_ organization) for agents and integrations. Use when a Hemlo call returns 401/forbidden, when setting up the Hemlo MCP server or API for the first time, or when the user asks about Hemlo access, scopes or keys.
license: Proprietary
metadata:
  author: hemlo
  version: "1.0"
---

# Hemlo API keys

| Prefix | Acts as | Created by |
| --- | --- | --- |
| `hsk_u_…` | The broker who created it (their deals, meetings, listings, Stilprofil) | Any broker |
| `hsk_o_…` | The firm's integration account | Hemlo Admin, per organization |

Scopes (pick the least that works):

| Scope | Allows |
| --- | --- |
| `me:read` | `get_me` only (default) |
| `deals:read` | Read deals, meetings, tasks, listings, style profiles |
| `deals:write` | Everything a broker can do: create/edit/capture/approve |

An agent that should do the broker's work needs `me:read deals:read deals:write`.

## Create a key

1. The broker signs in to Hemlo Admin → **API keys & agents** and clicks *Create key*, chooses
   scopes and copies the secret. It is shown once.
2. Or, with a signed-in session token:
   ```bash
   curl -s https://api.staging.hemlo.ai/api/v1/api-keys \
     -H "Authorization: Bearer <supabase-access-token>" \
     -H "Content-Type: application/json" \
     -d '{"name":"Claude","scopes":["me:read","deals:read","deals:write"]}'
   ```

## Store it

Put the key in the client's secret store or MCP header config, or an env var such as
`HEMLO_API_KEY`. Do not echo it, commit it or paste it into chat. Ask the broker to set it
themselves when the client supports that.

## Check it

`GET /api/v1/me` → `auth: { method: "api_key", scopes: [...], api_key_id }`.
401 = wrong/revoked key; `forbidden` = missing scope or role.

## Revoke

Hemlo Admin → API keys & agents → *Revoke*, or `DELETE /api/v1/api-keys/{id}`. Revoke right away if
a key may have leaked, then create a new one.