Autenticação da API

Selo de estado: Preview — a autenticação por chave habilita superfícies Preview (OData/Power BI/Excel) e a API de consulta REST, esta fora de GA hoje. Atualizado em 2026-09-06.

Todas as rotas /api/v1/** (REST e OData) usam a mesma autenticação: uma chave de API escopada ao workspace que a emitiu.

Disponibilidade#

• Planos: conforme o plano do workspace (a exposição da API externa pode ser liberada por plano/entitlement). Veja Planos.
• Região: Brasil (São Paulo).
• Estado operacional: o mecanismo de chave é Preview. As chaves de dados autenticam o feed OData (Preview); a API de consulta REST que elas também destravam está fora de GA (ver API de consulta).

Permissões#

• Só o dono (owner) do workspace cria e revoga chaves (em Configurações → Chaves de API). Isso é intencional e é a contenção principal: a chave lê todos os marts publicados do workspace.
• Escopo = workspace, não usuário. Diferente do acesso ao BI (que respeita grupos/segurança por linha por membro), a chave de dados não aplica recorte por membro nem máscara por usuário — ela consome o mart inteiro. Colunas marcadas como PII no catálogo nunca saem pela API (nem no $metadata).
• Toda resposta carrega X-Ingestia-Access-Scope: workspace sinalizando isso.
• Papéis (RBAC): a chave de dados padrão equivale ao papel owner e passa em todas as ações de dados. Credenciais de service principal carregam um papel no próprio envelope e podem ser negadas (403) em ações acima do seu nível (ex.: um service principal viewer tentando rodar SQL livre).

Configuração (como usar a chave)#

Envie a chave em um destes lugares:

1. Cabeçalho Authorization (recomendado — a URL não carrega segredo):

GET /api/v1/odata HTTP/1.1
Host: ingestia.io
Authorization: Bearer ing_live_<SUA_CHAVE_DE_API>

2. Parâmetro de query ?api_key= (ou ?key=) — necessário quando o cliente não deixa configurar cabeçalhos (Power BI/Excel embutem a chave na URL do feed):

https://ingestia.io/api/v1/odata?api_key=ing_live_<SUA_CHAVE_DE_API>

Atenção: com a chave na URL, o link vira um segredo — quem tiver o link lê os marts do workspace. Prefira o cabeçalho sempre que possível.

O valor cru da chave (prefixo ing_live_) aparece uma única vez, na criação. Guarde-o com segurança; se perder, gere outra e revogue a antiga.

Validação (como confirmar que funcionou)#

• Uma chamada autenticada ao service document responde 200 com a lista de tabelas:

  bashCopy

  curl -H "Authorization: Bearer ing_live_..." https://ingestia.io/api/v1/odata

• Sem chave → 401 { "error": "Chave de API ausente..." }.

• Chave inválida/revogada → 401 { "error": "Chave de API inválida ou revogada." }.

• O lastUsedAt da chave é atualizado a cada uso (visível na tela de chaves).

Exemplo#

O dono cria a chave ing_live_…, guarda-a como variável de ambiente do seu servidor de integração e a usa no cabeçalho Authorization para listar tabelas e puxar linhas do feed OData no Power BI. Se a chave vazar, ele a revoga na UI — toda chamada com ela passa a responder 401 na hora.

Custo#

• Criar/revogar chave: R$ 0.
• Autenticar não custa; o que custa é extrair linhas (ver API de consulta e OData). O valor em BRL exibido em x-ingestia-cost-brl é uma projeção.

Segurança#

• Chave guardada como hash no servidor; o valor cru só existe no seu lado.
• Isolamento por workspace: a chave só resolve o workspace que a emitiu; não há como uma chave ler dados de outro cliente.
• Rotação/revogação imediatas: revogar corta o acesso na hora.
• Nunca comite a chave em repositório nem a exponha no navegador do usuário final.

Limites#

• Uma chave = todo o mart do workspace. Não há hoje recorte por membro/grupo neste canal (chave por membro com segurança por linha está no Roadmap).
• Rate limit aplicado por chave e por workspace (ver Erros e limites) — uma chave não fura o teto do workspace.
• A criação de chaves é ação de dono; membros/visualizadores não criam chaves.

Troubleshooting#

Próximos passos: OData/Power BI · Embed SDK · Erros e limites.

Estado & evidência: mecanismo de chave = Preview; escopo de nível workspace por design (só o dono cria/revoga). Fonte: matriz de estados do produto.