Autenticação

A API do Dashboard Mágico usa um access token da Conta Kobana para autenticar todas as requisições.

O token

O token é um JWT RS256 emitido pelo Authorization Server da Kobana (account.kobana.com.br). Esta API apenas o verifica, contra a chave pública que aquele servidor publica — ela não guarda chave de assinatura e não consegue emitir token nenhum. A claim org identifica a sua organização: todos os dados retornados são automaticamente escopados a ela.

Requisitos conferidos a cada requisição:

Claim	Exigência
`iss`	O identificador do Authorization Server, como URL: `https://account[.{env}].kobana.com.br`
`aud`	A URL desta API: `https://api.pages[.{env}].kobana.com.br`. Pode ser uma lista — a regra é contém, não igualdade
`exp`	Obrigatória. Token sem expiração é recusado
`org`	A conta Kobana em cujo nome o token age — é ela que resolve a organização aqui, e é obrigatória
`sub`	A pessoa (`users.public_id`). Vai para auditoria e atribuição; não escopa nada
`jti`	Id único do token — base da revogação e da auditoria

:::caution Mudança em relação à chave de API Até setembro de 2026 a credencial era uma chave criada no dashboard (kb_…), com prefix público e secret exibido uma única vez. A chave era ao mesmo tempo a credencial e o que a verificava — quem lesse o repositório de chaves agia como qualquer organização, e cada rotação era uma conversa com um cliente. Agora quem emite é o Authorization Server, e a plataforma só verifica. Uma chave criada em Configurações → API não autentica mais esta API. :::

Confira o ambiente

O token é diferente entre Sandbox e Produção — o aud de um não vale no outro. Não reutilize entre ambientes.

Como enviar o token

Inclua o cabeçalho Authorization: Bearer <token> em cada requisição.

export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx

curl -i \
  -H "Authorization: Bearer $KOBANA_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Meu Nome (meunome@example.com)' \
  -X GET 'https://api.dashboards.sandbox.kobana.com.br/v1/organization'

Requisição válida

Com um token válido, a resposta traz dados da Organização autenticada.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Request-Id: req_01HABCDEF

{
  "id": "org_01HORG",
  "name": "Minha Empresa",
  "email": "contato@minhaempresa.com.br",
  "document_type": "cnpj",
  "document_number": "12345678000190",
  "environment": "sandbox",
  "created_at": "2026-01-01T00:00:00.000Z"
}

Requisição inválida

Token ausente, malformado ou revogado retorna 401 Unauthorized.

curl -i \
  -H "Authorization: Bearer tokeninvalido" \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Meu Nome (meunome@example.com)' \
  -X GET 'https://api.dashboards.sandbox.kobana.com.br/v1/organization'

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "invalid_token",
    "message": "Token de acesso inválido ou expirado."
  }
}

Códigos finos ajudam a achar o erro na hora: invalid_token (ausente, malformado ou assinatura inválida), invalid_audience (token de outro app Kobana), token_revoked e unknown_organization — este último é 403: o token é válido, a organização é que não está aqui.

Se o nosso Authorization Server estiver fora do ar, a resposta é 5xx, não 401. Isso é deliberado: um 401 mandaria você depurar uma credencial perfeita durante a nossa queda. Tente de novo em instantes.

:::note sub não é o tenant sub é a pessoa e org é a organização — são uuids de tabelas diferentes, então trocá-los não dá erro de formato. Um token sem org é recusado em vez de cair no sub: esse fallback não casaria com organização nenhuma e responderia 403 em tudo, com o sintoma apontando para permissão e não para a claim lida. :::

Escopos

Os escopos do token têm dois eixos ortogonais: o recurso, sempre prefixado pelo app (dashboards/users), e o verbo, um escopo global sem prefixo (write). Recurso sem verbo significa leitura. Escrever exige os dois: o escopo do recurso e o verbo.

Escopo	O que alcança
`dashboards/builder`	Construtor do portal: páginas, rascunho, publicação e versões
`dashboards/users`	Usuários do portal e o mapeamento que os gera
`dashboards/portal`	O portal: acesso, marca, visual, SEO, tracking, domínios e provedores de login
`dashboards/connectors`	Conectores (fontes de dados)
`dashboards/entities`	Entidades e seus registros
`dashboards/assets`	Biblioteca de arquivos
`dashboards/ai`	Uso e faturamento de IA
`dashboards/workspaces`	Workspaces
`dashboards/members`	Membros do dashboard, papéis e permissões
`dashboards/admin`	Organização e configurações, notificações e templates de e-mail, eventos, webhooks, auditoria, chaves de API, backups, exportações, importações, consumo e limites
Coringa do recurso	`dashboards/all` — lê todos os recursos acima, e não concede verbo nenhum
Verbo global	`write` — toda escrita (`POST`, `PUT`, `PATCH`, `DELETE`) nos recursos que o token carrega

Dois exemplos: dashboards/users lê usuários do portal e não escreve; dashboards/users write também convida, altera e exclui, e continua sem alcançar os membros do dashboard.

A forma granular dashboards/users:write é exceção da gramática, não o formato padrão: satisfaz os dois eixos para aquele recurso só, e existe para "lê um recurso, escreve outro". dashboards/* é curinga de cadastro e nunca é emitido num token — a comparação aqui é sempre literal. Não existe escopo read: leitura é o recurso sem verbo.

:::info Escopos ainda não são exigidos Os escopos acima já são o vocabulário desta API, mas ainda não são cobrados: eles precisam primeiro estar cadastrados no Authorization Server, e enquanto não estiverem, token nenhum em circulação carrega escopo — cobrar agora ou liberaria tudo (teatro) ou barraria todas as integrações vivas. Hoje o que vincula o token a esta API é o aud, que o verificador exige. Quando a cobrança entrar, faltar escopo passa a responder 403 insufficient_scope; peça desde já o escopo mínimo de cada integração para não precisar mexer depois. :::

Boas práticas

Nunca versione tokens em git. Use variáveis de ambiente ou cofres (AWS Secrets Manager, Vault, etc.).
Use tokens distintos por integração (CRM, ERP, frontend, etc.) — facilita revogar um sem derrubar os outros, e a auditoria por jti fica legível.
Peça os escopos mínimos necessários (princípio do menor privilégio) — recurso sem verbo quando a integração só lê.
Revogue imediatamente qualquer token vazado: a revogação é por jti e vale na chamada seguinte, sem esperar o exp.
HTTPS obrigatório — chamadas em HTTP são rejeitadas.

O token​

Como enviar o token​

Requisição válida​

Requisição inválida​

Escopos​

Boas práticas​