Saltar al contenido

Traducción automática — la versión en portugués es la referencia. Ver en portugués

Autenticación de la API

En esta página (9)

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: workspace para señalarlo.
  • Roles (RBAC): la clave de datos predeterminada equivale al rol owner y 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 principal viewer intentando 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):

http
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):

código
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 200 con la lista de tablas:

    bash
    curl -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 lastUsedAt de 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-brl es 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íntomaCausa probableQué hacer
401 Chave de API ausente (falta la clave)no enviaste la claveusa Authorization: Bearer <chave> o ?api_key=
401 Chave inválida ou revogada (inválida o revocada)clave incorrecta/revocadagenera una nueva clave en la UI (solo el dueño)
403 en SQL libre con service principalrol por debajo de adminusa la clave de datos del dueño o eleva el rol
La clave "desapareció" después de crearlael valor bruto solo aparece 1 vezgenera otra clave y revoca la anterior

Próximos pasos: OData/Power BI · Embed SDK · Errores y límites.

Enlaces relacionados