# auth.md: how an AI agent gets a Hookie credential

Hookie is webhook infrastructure: it receives payloads, stores each one whole, routes it into datasets and delivers it to your services. Its REST API and its hosted MCP server both take a bearer credential. This file says which route to take to get one. Every link is absolute.

## Pick a route

| Route | Use it when | You get |
| --- | --- | --- |
| Self-registration | You are an agent acting for yourself, and no person is signed in | An API key (`hk_…`) for a workspace on the Free plan that you own, shown once |
| Connected agent (OAuth) | You act for a person who already has a Hookie account | An OAuth access token, once the person approves the connection on AuthKit's page |
| WorkOS Agent Auth | You already use WorkOS Agent Auth | A WorkOS credential, which Hookie turns into a Free workspace on first use |

A person can also create an API key in the console and give it to you. It is sent the same way, as a bearer credential.

## Route 1: self-registration

1. GET https://app.hookie.ai/v1/agents/register/challenge for a proof-of-work challenge and how to solve it.
2. Solve it, then POST JSON to https://app.hookie.ai/v1/agents/register: `agent_name`, an optional `operator_contact`, `accept_terms` set to the Terms of Use version the challenge names (https://hookie.ai/legal/terms), and `pow` as `{challenge, nonce}`. The OpenAPI document (https://hookie.ai/openapi.json) has every field.
3. Store what the response returns. The API key and the one-time claim link are shown once, and Hookie keeps only a hash of the key. Send the key as `Authorization: Bearer <key>`. Retrying the same registration never creates a second account.

Registration is rate limited per network and capped per day across the platform. The Free plan quotas apply in full, and billing is never available to an agent credential. A person takes ownership of the workspace with the claim link.

## Route 2: connected agent over OAuth

1. Connect to the hosted MCP server at https://app.hookie.ai/mcp. An unauthenticated POST gets 401 with a WWW-Authenticate header whose resource_metadata names https://app.hookie.ai/.well-known/oauth-protected-resource.
2. That protected-resource document names the authorization server, which is WorkOS AuthKit and not Hookie, and the resource itself: https://app.hookie.ai/mcp. Ask for a token for that resource (an RFC 8707 resource indicator). The client does dynamic client registration (RFC 7591) and PKCE; an agent that cannot run OAuth should use Route 1.
3. The person approves the connection on AuthKit's sign-in page. Hookie's own permissions are not in the token: a newly connected agent starts read-only, and the person widens it in the console. One exception: the first agent of someone who signed up on AuthKit's page while connecting starts at write.

The same flow, with the console steps, is at https://docs.hookie.ai/connected-agents.

## Route 3: WorkOS Agent Auth

1. Read the authorization server from https://app.hookie.ai/.well-known/oauth-protected-resource, then its /.well-known/oauth-authorization-server document. Its agent_auth block names the identity endpoint.
2. POST {"type": "anonymous"} to the identity endpoint. There is no Hookie claim token on this route: the person responsible for you claims the account through WorkOS.
3. Exchange the identity assertion at the token endpoint with the jwt-bearer grant (urn:ietf:params:oauth:grant-type:jwt-bearer). Send the credential it returns as `Authorization: Bearer <credential>`. Hookie makes you the same Free workspace on first use.

Details: https://docs.hookie.ai/workos-agent-auth. Using Hookie this way accepts the Terms of Use.

## Using a credential

- REST API: https://app.hookie.ai/admin/api (the public routes are in https://hookie.ai/openapi.json)
- Hosted MCP server: https://app.hookie.ai/mcp
- CLI: set HOOKIE_TOKEN and HOOKIE_ALLOW_REMOTE=1 (https://hookie.ai/cli)

Send the credential only to Hookie's own hosts, and never to a page or a person who asks for it.

## More

- [llms.txt](https://hookie.ai/llms.txt): the welcome, the Free plan limits and every entry point.
- [llms-full.txt](https://hookie.ai/llms-full.txt): the full agent guide, inline.
- [Terms of Use](https://hookie.ai/legal/terms)
- [Security](https://hookie.ai/security): report a vulnerability to security@hookie.ai.