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 |
| 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 |
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: 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 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 oclient_iddentro 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).
| 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
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):
- 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":"..."}). - 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. - 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.
- 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, 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.