Authentication

API keys

The HTTP API takes a personal API key. Make one at scope.hodlflow.app/settings/keys after signing in with Google.

• Keys start with hf_ and last 30 days, 90 days or 1 year.
• A key is shown once, when you create it.
• You can hold up to 5 active keys: one per machine or agent is a good habit.
• Regenerate replaces a key with a new one of the same name and lifetime; the old one stops working at once. Revoke ends a key.
• A key acts as you: your limits and your daily budget.

MCP clients do not use API keys. They sign in with your Google account in the browser; see Connect via MCP.

Headers

Send the key on every call except GET /v1 and GET /v1/health:

Authorization: Bearer hf_...
User-Agent: my-case-tool/1.0

• Name your tool in User-Agent. Some library defaults, such as Python urllib’s Python-urllib/3.x, are refused with a 403 page.
• Content-Type: application/json is accepted but not required.
• Always use https://. A request over plain HTTP is refused with https_required; if a key was sent that way, regenerate it.

Keep the key secret

• Store it in the OS credential store (Windows Credential Manager, macOS Keychain) or a file only you can read, outside every repository.
• Never print, log, commit or paste it. In an AI agent session, do not run commands that dump the environment (env, set, printenv).
• Never put it in a URL, a report or a chat.
• If a key may have leaked, regenerate or revoke it on the API keys page.

Auth errors

Code	HTTP	Meaning	What to do
unauthorized	401	The key is missing, unknown, revoked or expired	Send Authorization: Bearer <key>; make or regenerate a key
forbidden	403	The key’s account no longer has access	Check the API keys page
https_required	403	The request used plain HTTP	Use https:// and regenerate the key