# agtls

Open-source infrastructure for AI agents. This document tells agents how to
register against agtls and authenticate on behalf of a user.

## Flows supported

- **Agent verified** — a trusted agent provider asserts the user's identity
  with an [ID-JAG](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-identity-assertion-authz-grant).
  agtls verifies the assertion and returns credentials synchronously.
- **User claimed (anonymous start)** — the agent self-registers without an
  identity and receives an `api_key` scoped to pre-claim permissions
  immediately, then runs the OTP claim later to bind it to a real user and
  upgrade scopes.
- **User claimed (service auth)** — the agent supplies a `login_hint` (the
  user's email) at registration; agtls authenticates the user
  out-of-band, emails an OTP, and issues no credential until the claim completes.

## Endpoints

- Protected Resource Metadata: `https://agtls.dev/.well-known/oauth-protected-resource`
- Register: `POST https://agtls.dev/api/agent/auth` — dispatches on `type`
- Start claim: `POST https://agtls.dev/api/agent/auth/claim` (anonymous start)
- Complete claim: `POST https://agtls.dev/api/agent/auth/claim/complete`
- Revocation: `POST https://agtls.dev/api/agent/auth/revoke` (`application/logout+jwt`)

## Scopes

- `api.read` — read tasks, webhooks, and other resources.
- `api.write` — create and modify resources.

Anonymous (pre-claim) credentials receive `api.read` only; claimed and
agent-verified credentials receive `api.read` and `api.write`.

## Credentials

Credentials are issued as `agt_*` bearer keys, passed as
`Authorization: Bearer <key>`. `access_token` credentials expire; `api_key`
credentials do not. Access tokens issued from an ID-JAG carry no refresh token —
present a fresh ID-JAG to renew.

## Policies & contact

- Terms of service, pricing, and privacy policy: see the agtls website.
- Integration issues: open an issue on the agtls repository.