Autenticação e permissões

Toda chamada envia uma credencial no cabeçalho:

Authorization: Bearer <chave de API ou token OAuth>

A credencial sempre age em nome de um usuário da equipe: o histórico, os logs e as notificações ficam registrados para ele, com o canal usado (api_key ou oauth).

Qual usar?

	Chave de API	OAuth 2.1
Uso típico	n8n, scripts, integrações servidor-a-servidor	Claude, ChatGPT, Cursor, aplicativos de terceiros
Como obter	Interface → Integrações → Gerar chave	O aplicativo abre a tela de login do Media Ops e você aprova
Permissões	Só as marcadas na criação	Todas as que o seu papel permite
Validade	30, 90, 180 ou 365 dias (ou sem expiração)	Token de 1 h, renovado automaticamente pelo aplicativo
Revogação	Integrações → Revogar (efeito em até 15 s)	Integrações → Remover acesso (imediato)

OAuth é o mais seguro para aplicativos e assistentes
Nenhum segredo de longa duração é copiado, o usuário aprova explicitamente e pode remover o acesso a qualquer momento. Use chaves de API apenas onde não há tela para login (automações).

Chaves de API

Formato: mops_ + 43 caracteres. A chave é exibida uma única vez; o servidor guarda apenas o hash SHA-256.
Guarde-a em um cofre de segredos (credenciais do n8n, variável de ambiente, gerenciador de segredos). Nunca a coloque em código, planilhas ou mensagens.
Uma chave não cria nem revoga outras chaves — isso exige login na interface.
Se uma chave vazar, revogue-a em Integrações e gere outra.

curl https://media.ops.infotrafego.com.br/api/v1/me \
  -H "Authorization: Bearer $MEDIA_OPS_API_KEY"

OAuth 2.1

O servidor de autorização é o Supabase Auth do Media Ops (código de autorização + PKCE, registro dinâmico de clientes habilitado). Aplicativos compatíveis descobrem tudo sozinhos a partir de:

Documento	URL
Metadados do recurso protegido (RFC 9728)	`/.well-known/oauth-protected-resource`
Metadados do servidor de autorização (RFC 8414)	`/.well-known/oauth-authorization-server`

Uma chamada sem credencial recebe 401 com WWW-Authenticate: Bearer resource_metadata="…", que é o ponto de partida da descoberta.

Fluxo, do ponto de vista do usuário:

o aplicativo abre …/auth/v1/oauth/authorize;
o Media Ops pede login (se necessário) e mostra a tela "Aplicativo quer acessar o Media Ops", com as permissões;
ao aprovar, o aplicativo recebe o token e passa a chamar a API/MCP em seu nome.

Permissões (escopos)

Escopo	Permite
`clients:read`	Ler clientes, BMs, contas de anúncio e ativos
`clients:write`	Cadastrar clientes e BMs, sincronizar ativos, ativar/desativar contas e arquivar clientes (arquivar exige administrador)
`balances:read`	Ler os saldos das contas de anúncio
`balances:write`	Atualizar os saldos
`meta:read`	Consultar a Meta e o Google Drive (públicos, interesses, localizações, formulários, publicações, campanhas, conjuntos, pastas)
`campaigns:read`	Ler execuções, progresso e logs
`campaigns:write`	Criar, estender e reexecutar campanhas
`audiences:read`	Ler criações de públicos
`audiences:write`	Criar públicos de engajamento
`templates:read`	Ler modelos de segmentação
`templates:write`	Criar, editar e remover modelos de segmentação
`admin:users`	Gerenciar usuários (somente administradores)

As permissões são sempre limitadas pelo papel atual do usuário: se um administrador perde o papel, suas chaves perdem admin:users na mesma hora. Chamar algo sem o escopo necessário retorna 403 com code: "insufficient_scope" e required_scope.

No MCP, o assistente só enxerga as ferramentas que as permissões liberam.