Skip to content

Automatic translation — the Portuguese version is the reference. View in Portuguese

API authentication

On this page (9)

The API key gives access to the OData feed (Power BI/Excel) and to the REST query API — the latter is unavailable for external use today.

All /api/v1/** routes (REST and OData) use the same authentication: an API key scoped to the workspace that issued it.

Availability#

  • Plans: depends on the workspace plan (external API exposure may be enabled per plan/entitlement). See Plans.
  • Region: Brazil (São Paulo).
  • Status: the key mechanism and the OData feed it authenticates are available; the REST query API the keys also unlock is in early access (see Query API).

Permissions#

  • Only the workspace owner creates and revokes keys (in Settings → API keys). This is intentional and is the main containment: the key reads all published marts in the workspace.
  • Scope = workspace, not user. Unlike BI access (which respects groups/row-level security per member), the data key does not apply per-member filtering or per-user masking — it consumes the entire mart. Columns flagged as PII in the catalog never leave through the API (not even in $metadata).
  • Every response carries X-Ingestia-Access-Scope: workspace to signal this.
  • Roles (RBAC): the default data key is equivalent to the owner role and passes all data actions. Service principal credentials carry a role in their own envelope and can be denied (403) on actions above their level (e.g., a viewer service principal trying to run free-form SQL).

Setup (how to use the key)#

Send the key in one of these places:

1. Authorization header (recommended — the URL carries no secret):

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

2. ?api_key= (or ?key=) query parameter — required when the client doesn't let you set headers (Power BI/Excel embed the key in the feed URL):

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

Warning: with the key in the URL, the link becomes a secret — anyone with the link can read the workspace marts. Prefer the header whenever possible.

The raw key value (prefix ing_live_) is shown only once, at creation. Store it securely; if you lose it, generate another one and revoke the old one.

Validation (how to confirm it worked)#

  • An authenticated call to the service document returns 200 with the list of tables:

    bash
    curl -H "Authorization: Bearer ing_live_..." https://ingestia.io/api/v1/odata
  • No key → 401 { "error": "Chave de API ausente..." } (API key missing).

  • Invalid/revoked key → 401 { "error": "Chave de API inválida ou revogada." } (invalid or revoked API key).

  • The key's lastUsedAt is updated on every use (visible on the keys screen).

Example#

The owner creates the key ing_live_…, stores it as an environment variable on their integration server, and uses it in the Authorization header to list tables and pull rows from the OData feed in Power BI. If the key leaks, they revoke it in the UI — every call using it starts returning 401 immediately.

Cost#

  • Creating/revoking a key: R$ 0.
  • Authenticating is free; what costs money is extracting rows (see Query API and OData). The BRL amount shown in x-ingestia-cost-brl is a projection.

Security#

  • The key is stored as a hash on the server; the raw value only exists on your side.
  • Workspace isolation: the key only resolves the workspace that issued it; there is no way for a key to read another customer's data.
  • Immediate rotation/revocation: revoking cuts off access instantly.
  • Never commit the key to a repository or expose it in the end user's browser.

Limits#

  • One key = the entire workspace mart. There is currently no per-member/group filtering on this channel (per-member keys with row-level security are on the Roadmap).
  • Rate limit applied per key and per workspace (see Errors and limits) — a key can't exceed the workspace ceiling.
  • Creating keys is an owner action; members/viewers can't create keys.

Troubleshooting#

SymptomLikely causeWhat to do
401 Chave de API ausente (key missing)the key wasn't sentuse Authorization: Bearer <chave> or ?api_key=
401 Chave inválida ou revogada (invalid or revoked)wrong/revoked keygenerate a new key in the UI (owner only)
403 on free-form SQL with a service principalrole below adminuse the owner's data key or raise the role
Key "disappeared" after creationraw value is shown only oncegenerate another key and revoke the previous one

Next steps: OData/Power BI · Embed SDK · Errors and limits.

Related links