Autenticação

A API REST do TagServer autentica por token Bearer. Há dois tipos de token, com escopos diferentes. Para o passo a passo de obter um token e fazer a primeira chamada, veja Início rápido.

Tipos de token

Token	Como obter	Prova	Validade
user token (`user_tokens`)	`POST /user-tokens`, com HTTP Basic (e-mail e senha) ou com o código de um login social	quem você é (não uma conta)	14 dias
token de conta (`tokens`)	`POST /tokens` enviando um user token válido e o `account_name`	acesso a uma conta específica	14 dias (padrão)

POST /tokens aceita um valid_until opcional que torna o token de longa duração (válido até a data informada) e o força a ReadOnly, qualquer que seja o papel do usuário na conta. O passo a passo está em Token de longa duração.

O token aparece uma única vez, na resposta da criação: o servidor guarda apenas um hash, nunca o token em si. Se perder, gere outro.

Obter um token

Método e rota	Autenticação	O que faz
`POST /user-tokens`	HTTP Basic (e-mail e senha), ou Bearer com um código de login	Cria um user token. Retorna `{ token, valid_until, user_email }`.
`POST /tokens`	user token (Bearer)	Recebe `{ "account_name": "..." }` e cria um token de conta para essa conta. Retorna `{ token, valid_until }`. Conta inexistente ou sem acesso retorna 400.
`GET /tokens/this`	token de conta (qualquer nível)	Confere se o token de conta atual é válido.
`DELETE /tokens/this`	user token (Bearer)	Exige user token e responde um booleano; não revoga tokens de conta.

O usuário entra por senha (password) ou por login social do Google (google). O HTTP Basic de POST /user-tokens (email:senha em base64) só funciona para quem tem senha: quem se cadastrou com o Google e não tem senha recebe 403 até definir uma.

Método e rota	Autenticação	O que faz
`GET /auth-methods`	user token (Bearer)	Lista os métodos de login do próprio usuário, mais antigos primeiro. Os segredos (hash de senha, id do provedor) nunca voltam.
`GET /auth-methods/{method}`	user token (Bearer)	Retorna um método. Responde 404 se o usuário não tem esse método.
`PUT /auth-methods/password`	user token (Bearer)	Recebe `{ "secret": "<senha>" }` e define ou troca a senha (ao menos 8 caracteres, sem `:`). É a mesma operação de `PUT /users/password`.
`DELETE /auth-methods/{method}`	user token (Bearer)	Remove um método. Remover o último método do usuário responde 400.

Nota

Vincular o Google a um usuário é feito no app, no card "Métodos de login". Se a identidade do Google já entra em outro usuário, a resposta é 409. O código de login usado como Bearer em POST /user-tokens vem do login social concluído no app: é de uso único e vale 60 segundos.

Enviar o token

Padrão: header Authorization: Bearer <token>.
Variante ?token=<token> na query string, para contextos em que a integração só aceita uma URL e não consegue definir o header Authorization: o CSV de relatórios consumido por uma ferramenta de BI num refresh agendado (Power BI, Looker Studio, Sheets), os streams SSE de eventos de provedor (Facebook, GA, Google Ads, TikTok, LinkedIn, Pinterest) e a exportação de tabela do FlowJutsu.

Níveis de acesso

Nível	Pode
ReadOnly (Somente Leitura)	Ler e listar recursos. Sem alterações.
Standard (Padrão)	Criar e editar recursos da conta (servidores, links, destinos, etc.), além de ler.
Admin (Administrador)	Tudo de Standard, mais as ações de nível de conta: gerenciar usuários (convidar, editar papel, remover), ver e cancelar a assinatura, renomear e excluir a conta. Concede papéis até Admin, nunca Owner.
Owner (Proprietário)	Tudo de Admin, mais transferir a propriedade da conta (`POST /accounts/this/owner`), a única ação exclusiva do Owner.

O privilégio é cumulativo: Owner abrange Admin, que abrange Standard, que abrange ReadOnly. Cada conta tem exatamente um Owner e pode ter vários Admin.

Escopo fixado na criação

Importante

O nível de acesso é gravado no token no momento em que ele é criado. Mudar o papel do usuário na conta não altera tokens já emitidos. Depois de mudar o papel, gere um novo token de conta.

Recursos por plano (feature flags)

Feature	Libera
`ServerSideApis`	Recurso da conta.
`AbTesting`	Recurso da conta.
`DataAnalytics`	Os dashboards de BI e as integrações de dados (fontes e onboarding de Google Analytics, Meta Ads e Google Ads, e a fila de jobs de integração).
`FlowJutsu`	O motor de fluxos (flows, parâmetros, projetos, tabelas, provisionamento, rhai, webhooks).
`Chat`	O chat.
`WebTracking`	As regras de tag (veja Regras de tag).

Por padrão, uma conta nova recebe apenas Chat. Alguns endpoints exigem que a conta tenha um recurso específico além do nível de acesso. Sem o recurso, a resposta é 403 com a mensagem do recurso ausente (Feature disabled: <recurso>). Cada página de recurso desta seção indica o feature que ela exige.

Respostas de autenticação

Código	Quando
`401 Unauthorized`	Credencial ausente ou mal formada (sem header `Authorization`, Basic ilegível).
`403 Forbidden`	Token inválido; usuário ou senha incorretos; privilégio insuficiente para o nível exigido; recurso (feature) desabilitado.

O formato geral do corpo de erro está em Convenções e erros.

Redefinição de senha

Método e rota	O que faz
`GET /password-reset-tokens?user_email=<email>`	Gera e envia por e-mail um token de redefinição para o usuário, válido por 1 hora. Sem usuário para o e-mail, responde 404.
`POST /password-reset-tokens`	Recebe `{ token, new_password }`, valida o token (uso único) e define a nova senha. O token é conferido primeiro: desconhecido, já usado ou expirado responde 404, mesmo que a senha seja inválida.

Com um token válido, uma nova senha com menos de 8 caracteres ou contendo : responde 400 (Invalid password) e nada muda.

Veja também

Início rápido: obter um token e fazer a primeira chamada.
Token de longa duração: gerar um token ReadOnly de longa duração com valid_until.
Convenções e erros: formato de erro e códigos.
Contas e usuários: a referência que usa estes níveis de acesso.