# auth.md

You are an agent. This service supports **agentic registration**: discover → register → (claim if needed) → exchange for an access_token / AppKey → call API → handle revocation. Follow the steps in order; do not skip ahead.

Web Agentic provides parcel tracking tools via MCP (Model Context Protocol) and REST APIs. It supports anonymous public tracking, owner-authorized self-registration for AI agents, and contracted access tiers with higher limits.

## Step 1 — Discover

Discovery is two hops:

1. **Protected Resource Metadata (PRM)**:
```http
GET /.well-known/oauth-protected-resource
```
Response:
```json
{
  "resource": "https://webagentic.labdx.org/",
  "resource_name": "Web Agentic",
  "resource_documentation": "https://webagentic.labdx.org/auth.md",
  "authorization_servers": ["https://webagentic.labdx.org"],
  "scopes_supported": ["mcp:read", "mcp:tools", "tracking:public", "tracking:contract"],
  "bearer_methods_supported": ["header"]
}
```

2. **Authorization Server Metadata**:
```http
GET /.well-known/oauth-authorization-server
```
Response:
```json
{
  "issuer": "https://webagentic.labdx.org",
  "authorization_endpoint": "https://webagentic.labdx.org/keys_manager.html",
  "token_endpoint": "https://webagentic.labdx.org/mcp/rastro/users_api.php?action=token",
  "registration_endpoint": "https://webagentic.labdx.org/keys_manager.html",
  "revocation_endpoint": "https://webagentic.labdx.org/mcp/rastro/users_api.php?action=revoke",
  "scopes_supported": ["mcp:read", "mcp:tools", "tracking:public", "tracking:contract"],
  "bearer_methods_supported": ["header"],
  "agent_auth": {
    "skill": "https://webagentic.labdx.org/auth.md",
    "register_uri": "https://webagentic.labdx.org/keys_manager.html",
    "identity_endpoint": "https://webagentic.labdx.org/mcp/rastro/users_api.php?action=identity",
    "claim_endpoint": "https://webagentic.labdx.org/keys_manager.html",
    "events_endpoint": "https://webagentic.labdx.org/mcp/rastro/users_api.php?action=event",
    "identity_types_supported": ["anonymous", "identity_assertion", "service_auth"],
    "identity_assertion": {
      "assertion_types_supported": ["urn:ietf:params:oauth:token-type:id-jag", "verified_email"],
      "credential_types_supported": ["app_key", "bearer_token"]
    },
    "anonymous": {
      "credential_types_supported": ["app_key", "session"]
    },
    "events_supported": [
      "https://schemas.workos.com/events/agent/auth/identity/assertion/revoked"
    ]
  }
}
```

## Step 2 — Pick a method

Use this decision tree:

1. **You have a session tied to a user identity and can exchange it for an ID-JAG, audience-bound to this service** → [identity_assertion + id-jag](#identity_assertion--id-jag).
2. **You have only the user's email** → [service_auth](#service_auth). Claim ceremony required.
3. **You have neither or require instant public tracking** → [anonymous](#anonymous). No registration or credentials needed for public tracking. Optional claim ceremony when your owner provisions a persistent AppKey.

## Step 3 — Register

Before registering or provisioning credentials, an AI agent MUST ask its owner for explicit authorization and proceed only after confirmation.

### identity_assertion + id-jag

Mint the ID-JAG assertion with:
- `aud`: `https://webagentic.labdx.org/`
- `iss`: your provider issuer URL
- `email_verified: true`

POST the assertion to `agent_auth.identity_endpoint`:
```http
POST /mcp/rastro/users_api.php?action=identity
Content-Type: application/json

{
  "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
  "assertion": "<id_jag_token>"
}
```

### service_auth

For email-based agent authentication, submit user verification to `register_uri` (`https://webagentic.labdx.org/keys_manager.html`). Follow the claim process in Step 4.

### anonymous

Anonymous access is available immediately without registration.
- Scope: `tracking:public`
- Rate limit: 1 request every 30 seconds per IP
- Intranet tracking is unavailable anonymously.

To self-register a limited counter AppKey, complete the self-registration form at `register_uri` (`https://webagentic.labdx.org/keys_manager.html`). The counter key format is `mcp_sk_counter_<key>` with a rate limit of 1 request every 10 seconds.

## Step 4 — Claim (if required)

When transitioning from anonymous or completing `service_auth`:
1. The agent directs the owner to `claim_endpoint` (`https://webagentic.labdx.org/keys_manager.html`).
2. The owner authorizes the client creation.
3. The server associates the generated AppKey with the agent or customer account.

## Step 5 — Exchange for an access_token

For JWT/ID-JAG assertions, exchange at `token_endpoint`:
```http
POST /mcp/rastro/users_api.php?action=token
Content-Type: application/json

{
  "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
  "assertion": "<identity_assertion>"
}
```

For provisioned AppKeys, the key itself acts as the bearer token (`mcp_sk_<key>` or `mcp_sk_counter_<key>`).

## Step 6 — Call the API

Send the token or AppKey in the `Authorization` or `X-App-Key` header over HTTPS.

### MCP (Model Context Protocol) JSON-RPC

Endpoint: `POST https://webagentic.labdx.org/mcp/rastro/index.php`

**Registered Counter Client**:
```http
POST https://webagentic.labdx.org/mcp/rastro/index.php
Content-Type: application/json
Authorization: Bearer mcp_sk_counter_<key>

{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}
```

**Contracted Client (Tier 3 - SRO Intranet & Tabela)**:
```http
POST https://webagentic.labdx.org/mcp/rastro/index.php
Content-Type: application/json
X-App-Key: mcp_sk_<key>
X-Cartao-Postagem: <customer_posting_card>

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"rastreamento_real_tabela","arguments":{"codigo":"NN074580571BR","app_key":"mcp_sk_<key>"}}}
```

**Anonymous Client**:
```http
POST https://webagentic.labdx.org/mcp/rastro/index.php
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}
```

## Step 7 — Handle revocation

An administrator or owner can revoke credentials via `revocation_endpoint`:
```http
POST /mcp/rastro/users_api.php?action=revoke
Content-Type: application/json

{
  "token": "mcp_sk_<key>"
}
```
Or by deleting/disabling the key in `https://webagentic.labdx.org/keys_manager.html`. When receiving HTTP 401, clear stored credentials and re-execute Step 1.

---

## Admin Panel Authentication

The `keys_manager.html` panel uses an internal session authentication API:
- Endpoint: `POST /mcp/rastro/users_api.php?action=auth`
- Body: `{"username": "admin", "password": "<password>"}`
- Authenticated calls send: `Authorization: Bearer <session_token>`
- Administrative actions: `list` (GET), `delete` (DELETE), `logout` (POST).
- Do not use administrative credentials as agent API keys.

## Discovery Metadata Summary

- **Protected Resource Metadata**: `https://webagentic.labdx.org/.well-known/oauth-protected-resource`
- **OAuth Authorization Server**: `https://webagentic.labdx.org/.well-known/oauth-authorization-server`
- **OpenID Configuration**: `https://webagentic.labdx.org/.well-known/openid-configuration`
- **API Catalog (RFC 9727)**: `https://webagentic.labdx.org/.well-known/api-catalog`
- **MCP Discovery**: `https://webagentic.labdx.org/.well-known/mcp-discovery.json`
- **MCP Endpoint**: `https://webagentic.labdx.org/mcp/rastro/index.php`
- **AppKey Management**: `https://webagentic.labdx.org/keys_manager.html`