# auth.md — Riffas

Instruções de autenticação para agentes que consomem dados do Riffas
(software de gestão de campanhas de rifa online, https://riffas.com.br).

## Para quem é este documento

Agentes e integrações automatizadas que precisam ler dados do Riffas —
buscadores de rifa, assistentes de produtor e painéis de parceiro.

## 1. Comece sem credencial

A maior parte do que um agente precisa é **público e não exige
autenticação**:

- `GET https://api.riffas.com.br/api/v1/raffles?status=active` — rifas ativas
- `GET https://api.riffas.com.br/api/v1/raffles/{slug}` — detalhe de uma rifa
- `GET https://api.riffas.com.br/api/v1/categories` — categorias
- `GET https://api.riffas.com.br/api/v1/pricing-tiers` — taxa fixa de ativação por faixa
- Servidor MCP: `https://riffas.com.br/mcp` (card em `https://riffas.com.br/.well-known/mcp/server-card.json`)
- Markdown de qualquer página: `Accept: text/markdown`

Só peça credencial se precisar de dado que não está aí.

## 2. Descoberta

| Documento | URL |
| --- | --- |
| Recurso protegido (RFC 9728) | `https://riffas.com.br/.well-known/oauth-protected-resource` |
| Servidor de autorização (RFC 8414) | `https://riffas.com.br/.well-known/oauth-authorization-server` |
| Catálogo de APIs (RFC 9727) | `https://riffas.com.br/.well-known/api-catalog` |
| Skills | `https://riffas.com.br/.well-known/agent-skills/index.json` |

O recurso protegido é a API do Riffas. Os tokens são **opacos**: a
validação acontece no resource server, não por verificação de assinatura —
por isso `https://riffas.com.br/.well-known/jwks.json` é publicado com lista de
chaves vazia.

## 3. Métodos de credencial suportados

### 3.1. Token de produtor — authorization code + PKCE

Para agir em nome de um produtor, nos dados da conta dele.

1. `authorization_endpoint`: `https://app.riffas.com.br/oauth/mobile/authorize` — o produtor
   autenticado autoriza o cliente na página de consentimento.
2. `token_endpoint`: `https://api.riffas.com.br/api/v1/auth/mobile/token` — troca de `code` +
   `code_verifier` (`code_challenge_method=S256`) pelo access token.
3. Uso: `Authorization: Bearer <access_token>`.

Não há **registro dinâmico de cliente**: `client_id` e `redirect_uri`
precisam estar previamente cadastrados em allowlist. Solicite o cadastro
como descrito em 3.3.

### 3.2. API key de parceiro

Para leitura agregada via API de parceiros:

```http
GET https://api.riffas.com.br/api/external/v1/raffles
X-Api-Key: <sua-api-key>
```

A chave também é aceita como `Authorization: Bearer <sua-api-key>`. Cada
chave tem escopo próprio e pode ter data de expiração.

### 3.3. Provisionamento (hoje: análise humana)

```http
GET https://riffas.com.br/api/agents/register
```

Devolve, em JSON, os campos exigidos e o canal de solicitação. **Não há
emissão automática de credencial**: um `POST` nesse endpoint responde
`501` com as mesmas instruções, de propósito — nenhuma credencial é
criada sem revisão.

Para solicitar acesso, escreva para **contato@riffas.com.br** com:

- nome do agente ou serviço e URL pública;
- responsável (nome, e-mail e, se houver, CNPJ);
- finalidade do acesso e dados que pretende ler;
- volume estimado de requisições e IPs de origem, se fixos;
- tipo de credencial desejada (token de produtor ou API key de parceiro).

## 4. Uso da credencial

- Envie a credencial **somente** para hosts do Riffas
  (`api.riffas.com.br`), sempre por HTTPS.
- Nunca coloque a credencial em query string, log ou página renderizada.
- Uma credencial por agente: não compartilhe entre integrações.
- Respeite `Cache-Control` e não repita a mesma leitura em loop.

## 5. Erros e revogação

| Status | Significado | O que fazer |
| --- | --- | --- |
| `401` | credencial ausente, inválida ou expirada | refaça a descoberta e o fluxo; não repita com a mesma credencial |
| `403` | escopo insuficiente | solicite ampliação do escopo pelo canal acima |
| `429` | throttle por IP | aguarde antes de tentar de novo |

Chaves e tokens podem ser revogados a qualquer momento (uso indevido,
encerramento de contrato ou pedido do produtor). Trate a revogação como
estado esperado e pare de tentar após `401` reincidente.

## 6. Limites de escopo

O Riffas é software de gestão: o pagamento é processado pelo gateway do
próprio produtor e o dinheiro nunca passa pela plataforma. **Não existe
API — pública ou autenticada — para movimentar valores, pagar afiliados ou
sortear em nome de um produtor por agente.** Dados pessoais de
participantes não são expostos sem autenticação do produtor dono da rifa.

Termos de uso: https://riffas.com.br/termos · Privacidade: https://riffas.com.br/privacidade