# auth.md

## tinysend agent authentication

tinysend supports agent authentication via the auth.md protocol.

### endpoints

- POST https://id.tinysend.com/agent/auth — register an agent
- POST https://id.tinysend.com/agent/auth/claim — claim identity for anonymous agents
- POST https://id.tinysend.com/agent/auth/claim/complete — verify OTP and upgrade permissions

### anonymous registration

```
POST https://id.tinysend.com/agent/auth
Content-Type: application/json

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

response:

```json
{
  "ok": true,
  "data": {
    "credential": "sk_...",
    "user_id": "usr_...",
    "claim_token": "ct_...",
    "scopes": ["read"]
  }
}
```

### identity assertion

```
POST https://id.tinysend.com/agent/auth
Content-Type: application/json

{
  "type": "identity_assertion",
  "assertions": [{ "type": "verified_email", "email": "user@example.com" }]
}
```

response:

```json
{
  "ok": true,
  "data": {
    "claim_token": "ct_...",
    "verification_required": true,
    "message": "Verification code sent to user@example.com"
  }
}
```

after receiving OTP, complete verification with POST https://id.tinysend.com/agent/auth/claim/complete (see below).

### claiming identity (upgrading permissions)

step 1 — request OTP:

```
POST https://id.tinysend.com/agent/auth/claim
Content-Type: application/json

{
  "claim_token": "ct_...",
  "email": "user@example.com",
  "link": false
}
```

- `link`: optional. if true, agent keeps its own identity linked to the human account. if false (default), agent merges into the human account.

response:

```json
{ "ok": true, "data": { "verification_required": true, "message": "Verification code sent to user@example.com" } }
```

step 2 — verify OTP:

```
POST https://id.tinysend.com/agent/auth/claim/complete
Content-Type: application/json

{ "claim_token": "ct_...", "otp": "123456" }
```

response:

```json
{
  "ok": true,
  "data": {
    "credential": "sk_...",
    "user_id": "usr_...",
    "scopes": ["read","write"],
    "mode": "merge"
  }
}
```

### scopes

- anonymous: read
- claimed: read, write
- human (OAuth): all scopes

### using credentials

include the credential in the Authorization header:

```
Authorization: Bearer sk_...
```

API base: https://tinysend.com/v1/:owner/:space/...
MCP server: mcp.tinysend (same Bearer token)

### discovery

- GET https://tinysend.com/.well-known/oauth-protected-resource
- GET https://id.tinysend.com/.well-known/oauth-authorization-server
- GET https://id.tinysend.com/.well-known/agent-configuration (agent auth protocol)