# Aravo auth.md

Agent registration and authentication guide for **aravo.app** (time tracking
and invoicing SaaS). Audience: AI agents (Claude Code, Codex, Cursor, or any
MCP client) acting on behalf of an Aravo user.

Aravo does not issue agent credentials via OAuth. Agents authenticate with
**personal access tokens** (`aravo_pat_...`) obtained through a browser
pairing ceremony (RFC 8628 style: device code + user approval). The fastest
path is the official CLI; the raw HTTP flow is documented below.

## Quickstart (recommended)

```sh
npx aravo-agent setup
```

The CLI starts a pairing request, opens the approval page in the user's
browser, waits for approval, and stores the token locally with the MCP
configuration for your agent runtime.

## Manual pairing flow

1. **Start a pairing request** (unauthenticated, rate limited):

   ```http
   POST https://aravo.app/api/agent/pairing
   Content-Type: application/json

   { "clientInfo": "my-agent/1.0", "scopes": "read_write", "locale": "en" }
   ```

   Response: `userCode`, `deviceSecret` (keep private), `verifyUrl`,
   `pollIntervalSeconds`, `expiresAt`.

2. **Ask the user to approve**: send the user to `verifyUrl`
   (`https://aravo.app/panel/agentes/autorizar?code=<userCode>`). The user
   signs in to their Aravo account and approves or denies the request.

3. **Claim the token** by polling (respect `pollIntervalSeconds`):

   ```http
   POST https://aravo.app/api/agent/pairing/claim
   Content-Type: application/json

   { "deviceSecret": "<deviceSecret>" }
   ```

   `202 {"status":"pending"}` until approved; then
   `200 {"status":"ready","token":"aravo_pat_...","scopes":"read_write"}`.
   The token plaintext is returned exactly once and never stored server-side
   (only its hash). Terminal states: `expired`, `denied`, `claimed`.

## Using the credential

Send the token as a Bearer token to the MCP server:

```http
POST https://aravo.app/api/mcp
Authorization: Bearer aravo_pat_...
```

The API is an MCP (Model Context Protocol) server: JSON-RPC over HTTP with
tools for time entries, tasks, clients, projects and reports, limited to the
approved user's data.

- Supported scopes: `read` (read-only) or `read_write` (requested at pairing).
- Identity type: the token acts as the approving user (no anonymous access).

## Revocation

- Users can revoke any token instantly in the panel: **Configuración →
  Seguridad** (`https://aravo.app/panel/configuracion`).
- Tokens can also be revoked programmatically by the authenticated user via
  `DELETE https://aravo.app/api/agent/tokens/{id}`.
- Revoked tokens fail immediately with `401 UNAUTHORIZED`.

## Discovery metadata

- MCP Server Card (SEP-1649): `https://aravo.app/.well-known/mcp/server-card.json`
- Protected resource metadata (RFC 9728): `https://aravo.app/.well-known/oauth-protected-resource`
- OIDC discovery of the user-auth issuer: `https://aravo.app/.well-known/openid-configuration`
- API catalog (RFC 9727): `https://aravo.app/.well-known/api-catalog`
- Site overview for LLMs: `https://aravo.app/llms.txt`
- Human documentation: `https://aravo.app/agentes/` (Spanish) /
  `https://aravo.app/en/agents/` (English)

## Errors

All API errors use:

```json
{ "error": { "code": "UNAUTHORIZED|VALIDATION|NOT_FOUND|DB_ERROR|PLAN_LIMIT|PLAN_REQUIRED", "message": "..." } }
```

Questions: hola@aravo.app