# auth.md

Authentication and access for **hitl.ph**. Callable human-in-the-loop infrastructure for AI agencies. One API call routes a task to a trained, accountable human and returns a structured result.

## Status

Early access — onboarding the first agencies. Request an API key via the access form.

Access is granted per organisation, not per agent, and keys are issued by a
human on the Yoonet team. There is no self-serve signup, no OAuth
authorisation server and no dynamic client registration today. An agent cannot
provision its own credential. If any of that changes, this document changes with
it.

## How to get a key

1. Request access at https://www.hitl.ph/#request-access, or email ai@yoonet.io.
2. Tell us which task types you expect to send (see below), roughly what volume,
   and which working window you need covered.
3. We reply with an API key and the base URL for your account.

Keys are long lived, tied to one account, and revoked on request.

## How to authenticate

Once you have a key, send it on every task request as a bearer token:

```
Authorization: Bearer <your-api-key>
```

The header `X-API-Key: <your-api-key>` is accepted as an alternative for
clients that cannot set an Authorization header. Keys are secrets: keep them
server side, never in a browser or a public repository.

## What you can call once authenticated

| Method | Path | Purpose |
| --- | --- | --- |
| POST | /tasks | Create a task for a human. |
| GET | /tasks/{id} | Read a task and its result. |
| PATCH | /tasks/{id} | Update or cancel a task. |

Task types accepted on the wire:

- `document.review`: Review a document. A trained person reads and decides on something a model should not sign off alone.
- `voice.call`: Make a phone call. Confirm a booking, chase a supplier, verify a detail — the jobs that still need a voice.
- `data.validate`: Validate ambiguous data. Resolve the records and judgement calls that models guess at and get wrong.
- `world.capture`: Take a photo, check the world. Confirm something physically exists or eyeball a real-world state and report back.
- `decision.own`: Make the call you can’t automate. An accountable human makes, signs and stands behind the decision — not a confidence score.

Full request and response shapes are documented at https://www.hitl.ph/docs/.

## Related documents

- Machine-readable summary: https://www.hitl.ph/llms.txt
- Full knowledge document: https://www.hitl.ph/llms-full.txt
- Open Knowledge Format bundle: https://www.hitl.ph/okf/index.md
- Agent skills index: https://www.hitl.ph/.well-known/agent-skills/index.json
- Human documentation: https://www.hitl.ph/docs/

## Contact

ai@yoonet.io