La clave de API da acceso al feed OData (Power BI/Excel) y a la API de consulta REST — esta última no está disponible para uso externo hoy.
Todas las rutas /api/v1/** (REST y OData) usan la misma autenticación: una
clave de API con alcance en el workspace que la emitió.
Disponibilidad#
- Planes: según el plan del workspace (la exposición de la API externa puede habilitarse por plan/entitlement). Consulta Planes.
- Región: Brasil (São Paulo).
- Estado: el mecanismo de clave y el feed OData que autentica están disponibles; la API de consulta REST que las claves también desbloquean está en acceso anticipado (consulta API de consulta).
Permisos#
- Solo el dueño (owner) del workspace crea y revoca claves (en Configuración → Claves de API). Esto es intencional y es la contención principal: la clave lee todos los marts publicados del workspace.
- Alcance = workspace, no usuario. A diferencia del acceso al BI (que respeta
grupos/seguridad por fila por miembro), la clave de datos no aplica recorte
por miembro ni enmascaramiento por usuario — consume el mart completo. Las columnas
marcadas como PII en el catálogo nunca salen por la API (ni en el
$metadata). - Toda respuesta lleva
X-Ingestia-Access-Scope: workspacepara señalarlo. - Roles (RBAC): la clave de datos predeterminada equivale al rol
ownery pasa todas las acciones de datos. Las credenciales de service principal llevan un rol en su propio envoltorio y pueden ser denegadas (403) en acciones por encima de su nivel (ej.: un service principalviewerintentando ejecutar SQL libre).
Configuración (cómo usar la clave)#
Envía la clave en uno de estos lugares:
1. Encabezado Authorization (recomendado — la URL no lleva el secreto):
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= (o ?key=) — necesario cuando el cliente
no permite configurar encabezados (Power BI/Excel incrustan la clave en la URL del feed):
https://ingestia.io/api/v1/odata?api_key=ing_live_<SUA_CHAVE_DE_API>Atención: con la clave en la URL, el enlace se vuelve un secreto — quien tenga el enlace lee los marts del workspace. Prefiere el encabezado siempre que sea posible.
El valor bruto de la clave (prefijo ing_live_) aparece una sola vez, al crearla.
Guárdalo de forma segura; si lo pierdes, genera otra y revoca la anterior.
Validación (cómo confirmar que funcionó)#
-
Una llamada autenticada al service document responde
200con la lista de tablas:bashcurl -H "Authorization: Bearer ing_live_..." https://ingestia.io/api/v1/odata -
Sin clave →
401 { "error": "Chave de API ausente..." }(falta la clave de API). -
Clave inválida/revocada →
401 { "error": "Chave de API inválida ou revogada." }(clave de API inválida o revocada). -
El
lastUsedAtde la clave se actualiza en cada uso (visible en la pantalla de claves).
Ejemplo#
El dueño crea la clave ing_live_…, la guarda como variable de entorno de su
servidor de integración y la usa en el encabezado Authorization para listar tablas y
traer filas del feed OData en Power BI. Si la clave se filtra, la revoca en la UI —
toda llamada con ella pasa a responder 401 al instante.
Costo#
- Crear/revocar clave: R$ 0.
- Autenticar no cuesta; lo que cuesta es extraer filas (consulta
API de consulta y OData). El valor
en BRL que se muestra en
x-ingestia-cost-brles una proyección.
Seguridad#
- La clave se guarda como hash en el servidor; el valor bruto solo existe de tu lado.
- Aislamiento por workspace: la clave solo resuelve el workspace que la emitió; no hay forma de que una clave lea datos de otro cliente.
- Rotación/revocación inmediatas: revocar corta el acceso al instante.
- Nunca hagas commit de la clave en un repositorio ni la expongas en el navegador del usuario final.
Límites#
- Una clave = todo el mart del workspace. Hoy no hay recorte por miembro/grupo
en este canal (la clave por miembro con seguridad por fila está en el
Roadmap). - Rate limit aplicado por clave y por workspace (consulta Errores y límites) — una clave no supera el tope del workspace.
- Crear claves es una acción del dueño; miembros/visualizadores no crean claves.
Troubleshooting#
| Síntoma | Causa probable | Qué hacer |
|---|---|---|
401 Chave de API ausente (falta la clave) | no enviaste la clave | usa Authorization: Bearer <chave> o ?api_key= |
401 Chave inválida ou revogada (inválida o revocada) | clave incorrecta/revocada | genera una nueva clave en la UI (solo el dueño) |
403 en SQL libre con service principal | rol por debajo de admin | usa la clave de datos del dueño o eleva el rol |
| La clave "desapareció" después de crearla | el valor bruto solo aparece 1 vez | genera otra clave y revoca la anterior |
Próximos pasos: OData/Power BI · Embed SDK · Errores y límites.