---
name: agtls
description: Authenticate with agtls on your own and use its agent infrastructure (tasks, webhook catchers) over REST or MCP. Use when you need a task list, an inbound webhook URL, or durable shared state without provisioning a backend.
---

# Using agtls as an agent

agtls (https://agtls.dev) is open-source infrastructure for AI agents. You do
not need a human to sign up: you can issue your own credential, work
immediately, and attach your work to a human's account later.

## 1. Get a credential (no human needed)

```
POST https://agtls.dev/api/agent/auth
Content-Type: application/json

{"type": "anonymous"}
```

The response contains:
- `credential` — an `agt_*` API key. Save it; it is shown once. Send it
  as `Authorization: Bearer <credential>` on every request.
- `claim_token` — save this too. A human uses it later to take ownership of
  your registration (see §4).

Pre-claim keys are read-only (`api.read`). If you need write access from the
start, either complete the claim (§4) or — when you know your user's email —
register with `{"type": "service_auth", "login_hint": "<user email>"}`
instead: the user receives an email, reads a one-time code back to you, and you
get a full-scope key bound to their account. Agents on trusted platforms can
present an ID-JAG (`{"type": "identity_assertion", "assertion_type":
"urn:ietf:params:oauth:token-type:id-jag", "assertion": "<jwt>"}`) and get a
full-scope credential synchronously. Full protocol details: https://agtls.dev/auth.md

## 2. Use the API

REST base: `https://agtls.dev/api` — JSON in/out, errors in a
`{"error": {"type", "code", "message"}}` envelope.

- `POST /api/tasks` `{"name": "...", "priority": "high", "labels": ["sprint-1"]}` — create a task
- `GET /api/tasks?label=sprint-1` — list tasks filtered by label
- `PATCH /api/tasks/{id}` `{"priority": "critical", "due_at": 1750000000}` — update a task
- `POST /api/webhooks` `{"name": "..."}` — get a URL that captures anything
  POSTed to it; read events back at `GET /api/webhooks/{id}/events`

MCP: connect to `https://agtls.dev/api/mcp` (streamable HTTP) with the same
`Authorization: Bearer` header. The same operations are exposed as tools. You
can also register entirely over MCP — call the `agent_register` tool (no
header needed) to get your `credential`, then pass it as the `api_key`
argument on every other tool call so your work is saved to your account.

## 3. Working without any credential

All write endpoints also work unauthenticated. Resources you create that way
are public (anyone with the ID can read/write them) and the creation response
includes a one-time `claim_token` for that resource. Later, any authenticated
caller can take ownership with:

```
POST https://agtls.dev/api/claim/{resource_id}
Authorization: Bearer <any agt_* key>

{"claim_token": "clm_..."}
```

## 4. Attaching your work to your human's account

When your operator wants your registration under their account, ask them for
their email, then:

```
POST https://agtls.dev/api/agent/auth/claim
{"claim_token": "<from registration>", "email": "<their email>"}
```

They receive an email link showing a 6-digit code. Have them read it to you,
then:

```
POST https://agtls.dev/api/agent/auth/claim/complete
{"claim_token": "<same token>", "otp": "<code>"}
```

Your existing key keeps working, upgraded to full scope. If their email matches
an existing agtls account, you join their organization as a member —
you and your human share the same resources from then on, and they can see you
on their dashboard. Humans can also sign up at https://agtls.dev/sign-up and create keys
for you in their dashboard.