API tokens

An API token is a secret that lets an agent into your Hamloy projects without signing in through a browser. Use one where nobody is there to press Allow: a server, a CI machine, a container, or a client that takes a header but has no sign-in step.

Most of the time you need none. Claude, ChatGPT, Codex, Claude Code and the hamloy program sign in through the browser, and you disconnect them under Connected apps. See Remote link or token for which to use.

Making one

On the Connect page, under API tokens:

1. Type what it is for, such as "Claude Code on the build server".
2. Press Make token.
3. Copy it from Your new token. It starts with hml_.

It is shown once. Hamloy keeps only a fingerprint of it, so it can't show it again; if you lose it, revoke it and make another. When you made it from a project's connect steps, those steps have it filled in.

Make one per machine or client. Then you can revoke one without stopping the others.

Using one

An agent sends the token in a header with every call:

Authorization: Bearer hml_…

For Claude Code, on one project's address:

claude mcp add --transport http hamloy https://hamloy.com/mcp/<the project's id> --header "Authorization: Bearer hml_…"

For Codex, which reads it from an environment variable each time it starts:

export HAMLOY_TOKEN=hml_…
codex mcp add hamloy --url https://hamloy.com/mcp --bearer-token-env-var HAMLOY_TOKEN

In a repo several people share, commit the address without the token, and let each person keep a token of their own in HAMLOY_TOKEN, in their shell profile, never in the repo:

{
  "mcpServers": {
    "hamloy": {
      "type": "http",
      "url": "https://hamloy.com/mcp/<the project's id>",
      "headers": { "Authorization": "Bearer ${HAMLOY_TOKEN}" }
    }
  }
}

The project's page on Connect shows these with its real address. The steps for each client are under Docs.

What a token reaches

A token is yours: it reaches every project you are on, your own and the ones shared with you, with what you may do there. The address decides which:

• https://hamloy.com/mcp/<the project's id>: that one project.
• https://hamloy.com/mcp: all of them, and every tool takes a project. See Projects.

What an agent does with a token is in the history as that agent, on your behalf: "claude", or "Sara's claude" on a shared project.

A token is for agents. It can't sign in to the board, change your account, or make other tokens.

Revoking one

Each token is listed with its name, its first and last characters (hml_…k3Pz), when it was made and when it was last used, or "never used". Revoke stops it at once: anything using it is refused from then on.

Revoke a token you no longer use, and one you might have shown to someone. Deleting your account revokes every token.

Limits

• A token doesn't expire. It works until you revoke it.
• A name is up to 80 characters.
• A token is shown once, when it is made.
• On the board, tokens are made only on the Connect page; agents can't make them.
• Keep a token out of repos, issues and chats; anyone with it acts as you in your projects.