Skip to content
MarkdownBots com IA

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ópriosToken de bot
Um app, site ou assistente que age como a pessoaOAuth, nesta página
Um agente que só sabe o e-mail da pessoa e não abre navegadorRegistro 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
TokenPOST 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.

EscopoO que a pessoa vê na tela de consentimentoRotas
user:readVer seu perfil e o de quem você conhece no ZynkoGET /users/@me, GET /users/{id}/profile
servers:readVer seus servidores, com canais e membrosGET /users/@me/guilds, GET /guilds/{id}/members, GET /guilds/{id}/emojis, GET /emojis/{id}, GET /channels/{id}/commands, GET /invites/{code}
servers:joinEntrar em comunidades públicas e aceitar convites por vocêPOST /communities/{handle}/join, POST /invites/{code}
messages:readLer 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:writeEnviar, editar e apagar suas próprias mensagens e reações, e marcar canais como lidosPOST /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:readVer seus amigos e pedidos de amizadeGET /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 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:

resourceVale na APIVale no MCP
https://zynko.orgsimsim
https://zynko.org/api ou https://zynko.org/api/v1simnão
https://zynko.org/mcp (o padrão, se faltar)simsim

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.

TokenFormatoValidade
Acessozyat_ + 64 hex1 hora
Renovaçãozyrt_ + 64 hex30 dias, trocado a cada uso
Código de autorizaçãozyac_ + 64 hex120 s, uso único
client_id registradozycl_ + 32 hexapagado 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).

OndeErroQuando
registroinvalid_redirect_uriEndereço de retorno que não é https nem http em loopback, ou mais de 10.
registroinvalid_client_metadataOutro problema nos dados do app.
tokeninvalid_requestFalta parâmetro ou o corpo está errado.
tokeninvalid_grantCódigo ou token de renovação vencido, usado ou revogado; redirect_uri ou code_verifier não confere.
tokeninvalid_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).
tokeninvalid_targetresource que não é do Zynko, ou que a autorização não cobre.
tokeninvalid_scopeA renovação pediu escopos que a pessoa não deu.
tokenunsupported_grant_typeTipo de concessão que o Zynko não tem.
autorizaçãoaccess_deniedA pessoa cancelou.
autorizaçãoinvalid_request, unsupported_response_type, invalid_targetPedido malformado (sem PKCE S256, response_type diferente de code, resource desconhecido). Volta para o app, com iss.
API401 unauthorizedSem token, ou token vencido ou revogado: renove uma vez.
API403 insufficient_scopeFalta um escopo. O cabeçalho WWW-Authenticate traz error="insufficient_scope" e, em scope, os escopos necessários.
API403 forbiddenA rota não abre para apps, ou a pessoa não tem permissão ali.
API429 rate_limitedEspere 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):

  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, 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.

Zynko · zynko.org