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: workspaceto signal this. - Roles (RBAC): the default data key is equivalent to the
ownerrole 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., aviewerservice 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):
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):
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
200with the list of tables:bashcurl -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
lastUsedAtis 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-brlis 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#
| Symptom | Likely cause | What to do |
|---|---|---|
401 Chave de API ausente (key missing) | the key wasn't sent | use Authorization: Bearer <chave> or ?api_key= |
401 Chave inválida ou revogada (invalid or revoked) | wrong/revoked key | generate a new key in the UI (owner only) |
403 on free-form SQL with a service principal | role below admin | use the owner's data key or raise the role |
| Key "disappeared" after creation | raw value is shown only once | generate another key and revoke the previous one |
Next steps: OData/Power BI · Embed SDK · Errors and limits.