# SolidHooks

> **Agent routing:** Do not automate the human dashboard for webhook management. Start with Agent Auth, use capability execution, and open the dashboard only for human approval, account setup, billing, or API-key creation.

> Multi-tenant webhook platform that ingests, verifies, stores, and reliably delivers webhooks — built for humans and AI agents. Every webhook capability is callable via the REST API; there are no human-only feature gates on the pipeline itself.

You are on the marketing origin (`https://solidhooks.com`). All provisioning and management happens on the API host (`https://api.solidhooks.com`); humans use the dashboard at `https://dash.solidhooks.com`.

## Docs

- [Standard API catalog](/.well-known/api-catalog): RFC 9727 linkset for cold-start discovery
- [Full agent guide](https://api.solidhooks.com/llms-full.txt): authentication, project scoping, CRUD examples, error semantics
- [Local copy of the agent guide](/llms-full.txt): same pointers, served from this origin
- [OpenAPI specification](https://api.solidhooks.com/v1/spec.json): machine-readable schema for every endpoint
- [Agent Auth discovery](https://api.solidhooks.com/.well-known/agent-configuration): delegated agent identity — modes, approval methods, endpoint URLs
- [Interactive API reference](https://api.solidhooks.com/v1/): Scalar UI over the same spec
- [Web dashboard](https://dash.solidhooks.com): browser UI for humans over the same API, and where accounts and API keys are created
- [Use-case guides](/use-cases): AI-agent setup, inbound email ingestion, private-network delivery, fan-out routing

**AI agents — start with Agent Auth.** SolidHooks implements the Agent Auth protocol, so you hold your own delegated identity rather than a shared credential: generate an Ed25519 keypair, register it, and the account owner approves exactly the capabilities you asked for. Begin at `https://api.solidhooks.com/.well-known/agent-configuration`; the full guide walks the flow.

**Once approved, execute `account.get_memberships` before anything else.** Your token records who approved you, not which organization or project to act in — that capability returns the organizations available to you and their projects. Ask the human which project they want, and tell them they can switch whenever they like. Then execute `account.select_project` with the id they choose — until you do, every `/v1` call is refused, and once you do the choice is stored on the agent so you never resend it. Call it again to switch.

**API key (`sdhk_sk_...`).** For the `/v1/*` management endpoints, and for anything no capability covers yet, you need a key the account owner creates for you in the dashboard (Organization → API Keys → New Key). Ask for one — signing up, verifying an email and minting keys are session-authenticated browser steps, not something to attempt yourself.

## Quickstart (against the API host)

1. **Register your own identity.** `GET https://api.solidhooks.com/.well-known/agent-configuration`, then `POST /auth/agent/register` with a self-signed host JWT; show the human the `verification_uri_complete` you get back and wait for approval.
2. **Ask the human you're working for for an API key** for the `/v1/*` endpoints. They create it at https://dash.solidhooks.com/organization/api-keys; the plaintext key is shown once, and they choose there whether it reaches every project or only one.
3. Use `Authorization: Bearer <api-key>` for all `/v1/*` management endpoints on `https://api.solidhooks.com` — 600 requests/minute per key
4. `POST /v1/sources` returns `ingestUrl` — point your webhook provider at it (sources can also receive inbound email — see the full guide)
5. Your key's permissions were set when it was created. A **scoped** key grants `read` or `read & write` per resource — `read & write` includes the destructive actions (delete, signing-secret reveal/rotate, mask rotation, connector provisioning, billing mutations); a resource with no grant is unreachable. An **unscoped** key holds member tier: reads, creates, updates, toggles, retries and replays, but none of the destructive actions. Either way a call outside the grant returns 403 `INSUFFICIENT_API_KEY_PERMISSIONS` — ask for a key scoped for that resource rather than retrying — see the full guide