# OAuth para apps e agentes

Um bot é uma conta própria, com o token dele. Quando um app ou um agente de IA precisa agir
**por uma pessoa** (ler as conversas dela, mandar uma mensagem em nome dela), ele usa OAuth
2.1: a pessoa entra no Zynko, vê o que o app pede e autoriza. O app recebe um token que só faz
o que foi autorizado e que a pessoa pode desligar quando quiser.

| Quero... | Use |
|---|---|
| Um bot que vive nos servidores, com nome e avatar próprios | [Token de bot](https://docs.zynko.org/bots/primeiro-bot.md) |
| Um app, site ou assistente que age como a pessoa | OAuth, nesta página |
| Um agente que só sabe o e-mail da pessoa e não abre navegador | [Registro de agentes](#agentes-sem-navegador) |

Clientes MCP como o Claude, o ChatGPT, o VS Code e o Claude Code já fazem todo o fluxo sozinhos
no [servidor MCP do Zynko](https://docs.zynko.org/bots/ia.md#servidor-mcp-remoto): basta adicionar `https://zynko.org/mcp`.

## Endereços

| | |
|---|---|
| **Emissor** (`issuer`) | `https://zynko.org` |
| **Metadados do servidor de autorização** (RFC 8414) | `https://zynko.org/.well-known/oauth-authorization-server` |
| **Metadados do recurso** (RFC 9728) | `https://zynko.org/.well-known/oauth-protected-resource` (e `/api`, `/api/v1`, `/mcp` no fim) |
| **Autorização** (no navegador) | `https://zynko.org/oauth/authorize` |
| **Token** | `POST https://zynko.org/api/v1/oauth/token` |
| **Registro de cliente** (RFC 7591) | `POST https://zynko.org/api/v1/oauth/register` |
| **Revogação** (RFC 7009) | `POST https://zynko.org/api/v1/oauth/revoke` |

As rotas de token, registro e revogação também respondem sem o `/v1` (`/api/oauth/token`).
Uma chamada sem token a uma rota protegida responde `401` com o cabeçalho que leva aos
metadados, e é assim que os clientes descobrem tudo sozinhos:

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://zynko.org/.well-known/oauth-protected-resource/api", scope="user:read servers:read messages:read messages:write"
```

## Escopos

Cada token carrega só os escopos que a pessoa autorizou, e só alcança as rotas desses escopos.
Sem `scope` no pedido, o app recebe `user:read servers:read messages:read messages:write`.
Escopos desconhecidos são ignorados.

| Escopo | O que a pessoa vê na tela de consentimento | Rotas |
|---|---|---|
| `user:read` | Ver seu perfil e o de quem você conhece no Zynko | `GET /users/@me`, `GET /users/{id}/profile` |
| `servers:read` | Ver seus servidores, com canais e membros | `GET /users/@me/guilds`, `GET /guilds/{id}/members`, `GET /guilds/{id}/emojis`, `GET /emojis/{id}`, `GET /channels/{id}/commands`, `GET /invites/{code}` |
| `servers:join` | Entrar em comunidades públicas e aceitar convites por você | `POST /communities/{handle}/join`, `POST /invites/{code}` |
| `messages:read` | Ler as mensagens dos canais e conversas que você vê | `GET /users/@me/channels`, `GET /channels/{id}/messages`, `GET /channels/{id}/posts`, `GET /attachments/{id}` (e `/thumb`) |
| `messages:write` | Enviar, editar e apagar suas próprias mensagens e reações, e marcar canais como lidos | `POST /channels/{id}/messages`, `PATCH`/`DELETE /channels/{id}/messages/{id}`, `PUT`/`DELETE .../reactions/{emoji}`, `POST /channels/{id}/typing`, `POST /channels/{id}/ack`, `POST /channels/{id}/posts`, `POST /users/@me/channels` |
| `friends:read` | Ver seus amigos e pedidos de amizade | `GET /users/@me/relationships` |

`user:read` abre o perfil da própria pessoa e o de quem divide um servidor, uma conversa ou uma
amizade com ela. Com um token de OAuth, `DELETE /channels/{id}/messages/{id}` só apaga as
mensagens da própria pessoa: a de outra pessoa responde `403 forbidden`, mesmo onde ela pode
gerenciar mensagens (moderar continua com ela, no Zynko). E `GET /users/@me/relationships` deixa
de fora quem a pessoa bloqueou: o app vê só os amigos e os pedidos pendentes.

Com qualquer escopo: `GET /config`, `GET /communities`, `GET /communities/{handle}`, o índice
`GET /api/v1`, `GET /openapi.json` e `GET /llms.txt`.

> **O resto da API não abre para apps**
>
> Configurar servidores, cargos, banimentos, voz, bots, pagamentos, a conta da pessoa e a
> exportação de dados ficam fora do OAuth: essas rotas respondem `403 forbidden` para um token de
> app, com qualquer escopo. O [gateway](https://docs.zynko.org/api/gateway.md) também não aceita tokens de OAuth; para
> acompanhar um canal, busque as mensagens novas com `GET /channels/{id}/messages?after=`.

## O fluxo: código com PKCE

Todo cliente é **público** (não existe segredo de cliente) e usa PKCE com `S256`.

### 1. Identifique o app

Há dois jeitos de ter um `client_id`:

- **Documento de metadados (CIMD).** Se o app publica um JSON com os dados dele numa URL
  https, essa URL é o `client_id`, sem registro nenhum. O Zynko busca o documento (só https,
  sem redirecionamento, até 5 s e 5 KB), confere que o `client_id` dentro dele é a própria URL
  e guarda em cache. É o que o Claude, o ChatGPT, o VS Code e o Claude Code usam.
- **Registro dinâmico (DCR, RFC 7591).** Mande os dados do app e receba um `client_id`
  (`zycl_` + 32 hex):

```http
POST /api/v1/oauth/register HTTP/1.1
Host: zynko.org
Content-Type: application/json

{
  "client_name": "Meu app",
  "redirect_uris": ["http://127.0.0.1/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}
```

A resposta é `201` com o `client_id`, o `client_id_issued_at` e os dados que você mandou. Os endereços de retorno
(`redirect_uris`, até 10) são https ou http em loopback (`127.0.0.1`, `[::1]`, `localhost`).
Em loopback **a porta não conta** na comparação: registre `http://127.0.0.1/callback` e use a
porta livre que quiser a cada execução. O registro tem limite por endereço. Um cliente
registrado que passa 30 dias sem nenhuma autorização ativa e sem autorizar nem renovar tokens é
apagado; se `/oauth/authorize` ou o endpoint de token disser que o cliente não existe
(`invalid_client`), registre de novo.

### 2. Peça a autorização

Gere um `code_verifier` aleatório (43 a 128 caracteres de `A-Z a-z 0-9 - . _ ~`) e o
`code_challenge`, que é o SHA-256 dele em base64url sem `=`:

```js
import { createHash, randomBytes } from 'node:crypto';

const verifier = randomBytes(32).toString('base64url');
const challenge = createHash('sha256').update(verifier).digest('base64url');
```

Abra no navegador da pessoa:

```
https://zynko.org/oauth/authorize?response_type=code
  &client_id=zycl_...
  &redirect_uri=http%3A%2F%2F127.0.0.1%3A53682%2Fcallback
  &scope=user%3Aread%20messages%3Aread%20messages%3Awrite
  &state=<aleatório>
  &code_challenge=<challenge>
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fzynko.org
```

(Tudo numa linha só; as quebras são só para ler.)

O `resource` (RFC 8707) diz onde o token vai ser usado:

| `resource` | Vale na API | Vale no MCP |
|---|---|---|
| `https://zynko.org` | sim | sim |
| `https://zynko.org/api` ou `https://zynko.org/api/v1` | sim | não |
| `https://zynko.org/mcp` (o padrão, se faltar) | sim | sim |

### 3. A pessoa autoriza

A pessoa entra no Zynko (se ainda não estiver) e vê a tela de consentimento: quem pede (o
endereço do app em destaque, com o selo "verificado" para clientes conhecidos, e um aviso para
apps no computador dela), com qual conta, os escopos e para onde ela vai voltar. O pedido vale
10 minutos.

- **Permitir** volta para `redirect_uri?code=zyac_...&state=...&iss=https%3A%2F%2Fzynko.org`.
- **Cancelar** volta com `error=access_denied&state=...&iss=...`.

Confira que o `state` é o seu e que o `iss` é exatamente `https://zynko.org`. Se o `client_id`
ou o `redirect_uri` estiverem errados, o Zynko mostra uma página de erro e **não** redireciona.

### 4. Troque o código pelo token

```http
POST /api/v1/oauth/token HTTP/1.1
Host: zynko.org
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=zyac_...&redirect_uri=http%3A%2F%2F127.0.0.1%3A53682%2Fcallback&client_id=zycl_...&code_verifier=...
```

```json
{
  "access_token": "zyat_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "zyrt_...",
  "scope": "user:read messages:read messages:write"
}
```

O `redirect_uri` tem que ser idêntico ao do passo 2, com a porta. O código vale 120 segundos e
uma vez só: usado de novo, ele derruba tudo o que gerou. O endpoint também aceita o corpo em
JSON, e toda resposta vem com `Cache-Control: no-store`.

### 5. Use e renove

```http
GET /api/v1/users/@me HTTP/1.1
Host: zynko.org
Authorization: Bearer zyat_...
```

O token de acesso vale **1 hora**. Para outro, use o de renovação, que vale **30 dias**:

```
grant_type=refresh_token&refresh_token=zyrt_...&client_id=zycl_...
```

Cada renovação devolve um par novo e mata o token de renovação usado. Apresentar de novo um
token de renovação já usado revoga a autorização inteira (é sinal de que ele vazou): guarde
sempre o mais novo. Dá para pedir um `scope` menor na renovação.

| Token | Formato | Validade |
|---|---|---|
| Acesso | `zyat_` + 64 hex | 1 hora |
| Renovação | `zyrt_` + 64 hex | 30 dias, trocado a cada uso |
| Código de autorização | `zyac_` + 64 hex | 120 s, uso único |
| `client_id` registrado | `zycl_` + 32 hex | apagado depois de 30 dias sem autorização ativa, sem autorizar e sem renovar |

## Apps conectados

A pessoa vê nos ajustes do Zynko, em **Apps conectados**, cada app e agente que tem acesso à
conta dela: o nome, o endereço, os escopos, quando foi autorizado e quando foi usado pela última
vez. **Desconectar** revoga a autorização e todos os tokens dela na hora.

O próprio app também pode largar o acesso (RFC 7009); a resposta é sempre `200`:

```http
POST /api/v1/oauth/revoke HTTP/1.1
Host: zynko.org
Content-Type: application/x-www-form-urlencoded

token=zyrt_...&token_type_hint=refresh_token&client_id=zycl_...
```

Revogar o token de renovação encerra a autorização inteira; revogar um token de acesso encerra
só ele.

## Erros

O endpoint de token responde no formato do OAuth, `{"error": "...", "error_description": "..."}`.
A API responde como sempre, `{"code": "...", "message": "..."}` (veja a
[visão geral](https://docs.zynko.org/api/index.md#erros)).

| Onde | Erro | Quando |
|---|---|---|
| registro | `invalid_redirect_uri` | Endereço de retorno que não é https nem http em loopback, ou mais de 10. |
| registro | `invalid_client_metadata` | Outro problema nos dados do app. |
| token | `invalid_request` | Falta parâmetro ou o corpo está errado. |
| token | `invalid_grant` | Código ou token de renovação vencido, usado ou revogado; `redirect_uri` ou `code_verifier` não confere. |
| token | `invalid_client` (401) | Cliente desconhecido (um cliente registrado parado por 30 dias é apagado: registre de novo), ou mandou segredo/asserção (clientes são públicos). |
| token | `invalid_target` | `resource` que não é do Zynko, ou que a autorização não cobre. |
| token | `invalid_scope` | A renovação pediu escopos que a pessoa não deu. |
| token | `unsupported_grant_type` | Tipo de concessão que o Zynko não tem. |
| autorização | `access_denied` | A pessoa cancelou. |
| autorização | `invalid_request`, `unsupported_response_type`, `invalid_target` | Pedido malformado (sem PKCE S256, `response_type` diferente de `code`, `resource` desconhecido). Volta para o app, com `iss`. |
| API | `401 unauthorized` | Sem token, ou token vencido ou revogado: renove uma vez. |
| API | `403 insufficient_scope` | Falta um escopo. O cabeçalho `WWW-Authenticate` traz `error="insufficient_scope"` e, em `scope`, os escopos necessários. |
| API | `403 forbidden` | A rota não abre para apps, ou a pessoa não tem permissão ali. |
| API | `429 rate_limited` | Espere o `Retry-After`. |

## Agentes sem navegador {#agentes-sem-navegador}

Um agente que não consegue abrir o navegador da pessoa nem receber o redirecionamento usa o
registro de agentes (`service_auth`, do protocolo auth.md da WorkOS):

1. O agente se registra com o e-mail da conta da pessoa em
   `POST https://zynko.org/api/v1/agent/identity` (`{"type":"service_auth","login_hint":"..."}`).
2. Ele recebe um link (`https://zynko.org/agent/claim?attempt=...`) e um código de 6 dígitos e
   passa os dois para a pessoa.
3. A pessoa abre o link, entra **com a conta daquele e-mail**, vê o nome do agente e os
   escopos, digita o código e autoriza. O código vale 10 minutos e aceita 5 erros.
4. Enquanto isso o agente consulta o endpoint de token; quando a pessoa autoriza, ele recebe
   um token de acesso e uma asserção, que troca por tokens novos durante 30 dias (até a pessoa
   desconectar o agente).

O agente aparece em **Apps conectados** como os apps. O passo a passo completo, com cada
requisição e cada erro, está em [zynko.org/auth.md](https://zynko.org/auth.md), escrito para os
próprios agentes. Registro anônimo e asserções de provedores de identidade (ID-JAG) não estão
habilitados.

## Para testar

Não há um ambiente de testes separado: use uma conta e um servidor seus, peça só os escopos que
for testar e desconecte o app no fim. Veja [zynko.org/sandbox](https://zynko.org/sandbox/).
