Escopo workspace; só o dono cria/revoga; PII nunca sai

Selo de estado: Preview (teto atual do produto) · Curso ACD-250 — Integrações e consumo externo · Aula 2 de 6 · Atualizado em 2026-10-04.

Objetivo#

Ao final desta aula você vai emitir e revogar chave — e explicar, em uma frase, por que uma chave de API do ingestia.io é uma credencial de serviço, nunca de pessoa.

Vídeo#

Identificador no manifesto: acd-250-02-chaves-de-api-e-escopo · duração-alvo 6 min · tela do produto: /connect.

Roteiro de gravação (5 capítulos):

Conteúdo#

Uma chave de API do ingestia.io autentica todas as rotas /api/v1/** — o feed OData, e também a API REST que hoje está fora de GA. Ela é o único mecanismo de credencial desse canal, e vale entender exatamente o que ela representa antes de criar a primeira: uma chave = leitura de todos os marts publicados do workspace que a emitiu. Não é a credencial da Maria; é a credencial do integrador da Aurora.

A contenção é o dono, não o escopo

Isso parece pouca granularidade, e é — de propósito, com uma contenção deliberada no lugar: só o dono (owner) do workspace cria e revoga chaves. Membros e visualizadores não criam. Como a chave consome o mart inteiro, a decisão de emiti-la sobe para quem responde pelo workspace.

Duas consequências que costumam surpreender quem vem do BI:

• Escopo = workspace, não usuário. O acesso ao BI nativo respeita grupos e segurança por linha por membro. A chave de dados não aplica recorte por membro nem máscara por usuário: ela lê o mart publicado inteiro. Chave por membro com segurança por linha é Roadmap.
• PII nunca sai pela API. Colunas marcadas como PII no catálogo não aparecem no feed — nem nas linhas, nem no $metadata, nem no catálogo de tabelas. Isso não é configuração por chave: é allowlist de governança, igual para toda credencial.

Para você não esquecer de qual canal está falando, toda resposta da API carrega o cabeçalho X-Ingestia-Access-Scope: workspace.

A tela: /settings → Integrações e chaves

A credencial nasce e morre num só lugar: /settings → Integrações e chaves, no cartão Chaves de API (área do dono). Nova chave pede um nome — e o nome importa de verdade, porque é por ele que você vai saber o que revogar meses depois; use algo como Power BI — Financeiro ou Excel — Maria, não teste. Ao criar, o valor cru (prefixo ing_live_) aparece uma única vez na tela, com o aviso de que não será exibido de novo: no servidor fica apenas o hash. Perdeu? Não há recuperação — gere outra e revogue a anterior.

Cada chave da lista mostra o prefixo, a data de criação e o último uso (lastUsedAt, atualizado a cada chamada) — é assim que você descobre qual chave ainda está viva antes de desligar alguma. O botão Revogar pede confirmação e avisa que as ferramentas que usam aquela chave perdem o acesso; o corte é imediato, e toda chamada posterior responde 401.

As telas /connect e /excel consomem essa chave. /connect monta a URL do feed com SUA_CHAVE no lugar da sua; /excel vai além e deixa você escolher uma chave existente para montar a URL já pronta para colar — com o aviso, em caixa destacada, de que essa URL é um segredo.

Os dois jeitos de enviar a chave

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

O cabeçalho Authorization é o recomendado: a URL não carrega segredo, então não vai para log de proxy, histórico de navegador ou print de tela. A alternativa é ?api_key= (ou ?key=) na URL, necessária quando o cliente não deixa configurar cabeçalho — é o caso do caminho simples de Power BI e Excel, que embutem a chave na URL do feed.

Exemplo: a Aurora Varejo

Maria é dona do workspace Aurora Varejo. Ela cria duas chaves, de propósito: Power BI — Financeiro, que vai para o servidor de integração como variável de ambiente e alimenta o relatório da diretoria, e Excel — Operações, que João usa na tabela dinâmica dele. Em novembro, João sai da empresa: Maria abre Integrações e chaves, confere que Excel — Operações foi usada ontem, clica Revogar e confirma. O Excel de João responde 401 na atualização seguinte; o Power BI do financeiro, que usa a outra chave, não sente nada. Duas chaves nomeadas valeram exatamente por isso — revogar uma sem derrubar a outra.

Erros comuns

Faça você mesmo#

No workspace de treino Aurora Varejo, como dona (abra /connect e depois /settings):

1. Em /connect, localize a URL base da API e o nome do dataset gold (aurora_gold). Use o atalho Gerenciar chaves para ir às configurações.
2. Em Integrações e chaves → Chaves de API, clique Nova chave e dê a ela um nome que você reconheceria em seis meses: Treino — Academy.
3. Copie o valor cru exibido e cole num bloco de notas temporário. Releia o aviso na tela: ele não será exibido de novo.
4. Confirme na lista que a chave aparece com prefixo, data de criação e último uso ainda vazio.
5. Valide a chave no único canal disponível hoje — o feed OData — chamando o service document com o cabeçalho (não com a chave na URL): curl -H "Authorization: Bearer <sua chave>" https://ingestia.io/api/v1/odata. Espere 200 com a lista de tabelas.
6. Volte à lista de chaves e confirme que o último uso agora está preenchido.
7. Clique Revogar na chave de treino e confirme. Repita a chamada do passo 5 e confirme que agora responde 401.
8. Apague o valor cru do bloco de notas. Escreva uma frase explicando por que criar uma chave por destino (uma para Power BI, outra para Excel) é melhor que uma chave para tudo.

Você terminou quando tiver emitido uma chave, visto 200 no service document, revogado a chave, visto 401 na mesma chamada — e conseguir explicar em uma frase por que essa chave é credencial de serviço e não de pessoa.

Checagem rápida#

Três perguntas no final da aula, corrigidas no servidor. A aula só conta como concluída depois da checagem.

Documentação relacionada#

• desenvolvedores/autenticacao

Capacidades ensinadas#

(conceitual — sem capacidade específica da matriz) — o selo exibido na aula é sempre o estado mais conservador entre as capacidades citadas; nada aqui é "GA".