# Torêva agent authentication

Torêva accepts agent traffic for public discovery, public site navigation and public company lookup pages without authentication.

Protected product APIs are owned by the Torêva app at `https://app.toreva.com.br`. Agents that need account-specific data or write access should start with the app registration and login flow.

## Discovery

- Agent instructions (when to use Torêva): `https://toreva.com.br/agent-instructions.md`
- Developer portal: `https://toreva.com.br/developers` (markdown mirror: `https://toreva.com.br/developers.md`)
- OAuth authorization server metadata: `https://toreva.com.br/.well-known/oauth-authorization-server`
- OAuth protected resource metadata: `https://toreva.com.br/.well-known/oauth-protected-resource`
- API catalog: `https://toreva.com.br/.well-known/api-catalog`
- Public API index (versioned): `https://toreva.com.br/api/v1`
- MCP server (Streamable HTTP, no auth): `POST https://toreva.com.br/.well-known/mcp`
- Domain map for language models: `https://toreva.com.br/llms.txt`

## Registration

- Register or create an account: `https://app.toreva.com.br/criar-conta`
- Existing account login: `https://app.toreva.com.br/login`
- API access for account data is granted case by case: write to `contato@toreva.com.br` with the intended scope. There is no self-service API key issuance yet.
- Support: `contato@toreva.com.br`

## Agent guidance

Use public discovery resources for read-only exploration. Request user authorization before attempting account-specific actions, lead export, CRM updates, or billing changes.

## Error handling

Every response under `/api/` is JSON, including errors, with a stable
`error.code`, an `error.message`, an `error.hint` and a `documentation` URL.
Unknown paths outside `/api/` return a real HTTP 404 (markdown body when the
request sends `Accept: text/markdown`), never a 200 with the app shell.

## Rate limiting

120 requests per minute per client, burst 60. Every response under `/api/`
carries `RateLimit-Limit`, `RateLimit-Reset` and `RateLimit-Policy`. On `429`,
respect `Retry-After` before retrying. Details:
`https://toreva.com.br/docs/api.md`.

## Versioning

The public API is versioned in the path: `/api/v1/`. Integrate against the
versioned path — `/api/` without a version is an alias of the current stable
release. Deprecation is signalled with `Deprecation` (RFC 9745) and `Sunset`
(RFC 8594) headers, with at least 180 days of notice. Policy:
`https://toreva.com.br/docs/versioning.md`.