OAuth 2.1

Com OAuth, uma pessoa autoriza o seu app a agir por ela em um workspace dela. O app recebe um access token que vale para a API (/api/v1) ou para o servidor MCP (/api/mcp) e alcança só o que os escopos concedidos e o papel da pessoa permitem.

O servidor de autorização é o do próprio Zaplin, com Authorization Code e PKCE (S256), registro dinâmico de clientes (RFC 7591) e resource indicators (RFC 8707).

EndpointsCopiar link

https://app.zaplin.com.br/.well-known/oauth-authorization-server/api/auth

Leia os endereços dos metadados em vez de fixá-los no código.

Registre o appCopiar link

Há dois jeitos:

Em Desenvolvedores → OAuth appsCopiar link

Owner e Admin criam apps em Configurações → Desenvolvedores → OAuth apps → Novo app OAuth:

• Nome: aparece na tela de consentimento.
• URIs de redirecionamento: uma por linha, de 1 a 10. HTTPS, ou HTTP em localhost, 127.0.0.1 ou [::1], sem fragmento (#).
• Escopos: os mesmos das chaves de API, pelo menos um.

O app recebe um client ID e um segredo cs_live_…, que aparece uma única vez. É um cliente confidencial: autentica no token com client_secret_basic, usa os grants authorization_code e refresh_token, e o PKCE é obrigatório.

Rotacionar segredo emite um segredo novo, e o antigo continua valendo por 24 horas para você trocar sem parar o app (Revogar agora encerra o antigo antes). Rotacionar pede que você tenha entrado nos últimos 10 minutos.

Registro dinâmicoCopiar link

Clientes como assistentes de IA se registram sozinhos com POST /api/auth/oauth2/register, sem login. O PKCE é obrigatório e não pode ser desligado. Esses clientes não aparecem em OAuth apps e não passam por verificação.

O fluxoCopiar link

import { createHash, randomBytes } from "node:crypto"

const verifier = randomBytes(32).toString("base64url") // guarde para o próximo passo
const challenge = createHash("sha256").update(verifier).digest("base64url")

const url = new URL("https://app.zaplin.com.br/api/auth/oauth2/authorize")
url.search = new URLSearchParams({
  response_type: "code",
  client_id: CLIENT_ID,
  redirect_uri: "https://seuapp.com/callback",
  scope: "contacts:read messages:write offline_access",
  state: STATE,
  code_challenge: challenge,
  code_challenge_method: "S256",
  resource: "https://app.zaplin.com.br/api/v1",
}).toString()
// mande o navegador para url.href

curl https://app.zaplin.com.br/api/auth/oauth2/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=CODE \
  -d redirect_uri=https://seuapp.com/callback \
  -d code_verifier=CODE_VERIFIER \
  -d resource=https://app.zaplin.com.br/api/v1

curl https://app.zaplin.com.br/api/v1/conversations?status=open \
  -H "Authorization: Bearer ACCESS_TOKEN"

O que um token alcançaCopiar link

• Os escopos concedidos, e só onde o membro tem a permissão correspondente (veja a tabela de escopos). Uma chamada fora disso recebe 403.
• As conversas, números e grupos que o membro vê pelo alcance dele (todo o workspace, as equipes dele ou só o que é atribuído a ele).
• O que o app faz aparece na auditoria em nome do app e da pessoa.

O token é conferido a cada chamada: se o app for desconectado, se a pessoa sair do workspace, perder o assento ou virar Viewer, a próxima chamada recebe 401.

Apps não verificadosCopiar link

Um app criado em OAuth apps nasce Não verificado e pode ser conectado ao workspace dono dele e a mais 10 workspaces. Para passar disso, peça a verificação em Pedir verificação, contando como o app usa os dados (e, se quiser, o site ou a documentação dele). O app fica Em análise até a equipe do Zaplin responder. Mudar as URIs de redirecionamento para outro domínio volta o app para Não verificado.

DesconectarCopiar link

Owner e Admin veem cada app autorizado no workspace em Configurações → Desenvolvedores → Apps conectados. Revogar acesso apaga a autorização e os refresh tokens; os access tokens param na próxima chamada.