# Auth.md

# UNO Collective — Agent Authentication

> Authentication for AI agents acting on behalf of their organization.
> Protocol: [auth.md](https://workos.com/auth.md) by WorkOS (open spec,
> not WorkOS-only). Source: 2026-06-21 IsItAgentReady audit recheck,
> finding "auth.md not found".

This file describes how AI agents authenticate to UNO Collective to use
the agentic API surface. It is read by agents and by humans integrating
with our service.

## Service

UNO Collective is a marketing and development agency with presence in
LATAM and the USA. We offer agentic work for: quotes, project tracking,
and contract lifecycle. The full surface is planned — see `/llms.txt`
v0.3 and the OpenAPI spec at `/api/openapi.yaml` for what is scoped.

## Supported flows

We support the **User Claimed** flow only.

- **User Claimed** (RFC 8628 device authorization grant): the agent
  requests a device code; the human contact visits a verification URL
  and approves the scopes; the agent polls for an `access_token`. The
  contact has full visibility into what the agent is asking for.

We do **not** support the **Agent Verified** flow today. That flow
requires integration with an external IdP that signs ID-JAGs (IETF
`draft-ietf-oauth-identity-assertion-authz-grant`), which is out of
scope for v0. If your organization needs verified-agent identity,
contact us.

## Scopes

| Scope | Description |
| --- | --- |
| `quotes:read` | List past quotes for your organization |
| `quotes:write` | Request a new quote (`POST /api/quote`) |
| `transactions:write` | Confirm a quote and open a project (`POST /api/transaction`) |
| `projects:read` | List your projects and read status (`GET /api/status/{project_id}`) |
| `projects:comment` | Post comments on a project (`POST /api/comment`) |
| `projects:approve` | Approve a milestone on a project (`POST /api/approve`) |

## Registration

```
POST https://www.unocollective.com/api/agent/claim
Content-Type: application/json
```

Request body:

```json
{
  "client_name": "Acme Inc",
  "contact_email": "[email protected]",
  "intended_scopes": ["quotes:read", "quotes:write", "projects:read"]
}
```

Response (RFC 8628 device authorization grant):

```json
{
  "device_code": "GmRx...",
  "user_code": "ABCD-1234",
  "verification_uri": "https://www.unocollective.com/claim",
  "expires_in": 1800,
  "interval": 5
}
```

The contact visits the `verification_uri`, enters the `user_code`, sees
the scopes the agent is requesting, and clicks **Approve** or
**Reject**. Once approved, the agent polls the token endpoint below.

## Token exchange

```
POST https://www.unocollective.com/api/oauth2/token
Content-Type: application/x-www-form-urlencoded
```

Form body:

```
grant_type=urn:workos:agent-auth:grant-type:claim&device_code=GmRx...
```

On approval:

```json
{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 7776000,
  "scope": "quotes:read quotes:write projects:read"
}
```

The `access_token` is scoped, short-lived (90 days), and revocable.
Send it on every agentic API call as `Authorization: Bearer <token>`.

## Revocation

```
POST https://www.unocollective.com/api/agent/revoke
Authorization: Bearer <token>
```

Empty body. Returns `200` on success. Use this when your project ends,
your agent is decommissioned, or the token is compromised.

## Errors

We follow RFC 8628 error codes for the device flow:

| Error | Meaning |
| --- | --- |
| `authorization_pending` | User has not yet approved. Keep polling. |
| `slow_down` | You are polling too fast. Wait `interval` seconds. |
| `expired_token` | `device_code` expired (1800s). Restart registration. |
| `access_denied` | User rejected the request. |

## Honest limitations (v0)

- The 4 endpoints quoted above (`/api/quote`, `/api/transaction`,
  `/api/status/{project_id}`, `/api/comment`, `/api/approve`) are
  **planned**, not shipped. They are scoped in `/llms.txt` v0.3 and
  the OpenAPI spec but blocked on internal decisions (pricing
  thresholds, CRM choice, language scope).
- The auth flow itself (`/api/agent/claim`, `/api/oauth2/token`,
  `/api/agent/revoke`) is also v0 — implementation is planned for
  the same milestone (H2) as the endpoints. This file declares the
  protocol so agents can be coded against it ahead of the launch.
- No machine-readable endpoint registry beyond this Markdown file.
  When the API surface is live, this file will be updated to include
  the actual URLs and any error responses discovered in production.

## Contact

For issues with agent auth: `joaquin@orange.sc`.
For security disclosures: see `/.well-known/security.txt`.