Autenticación | Documentación API Mapalyze

Autenticación

Claves API

Mapalyze utiliza claves API con alcance de organización para integraciones servidor a servidor.

Formatos de clave

mk_live_...: clave de producción.
mk_test_...: clave de sandbox/prueba.

Su gateway puede configurarse para aceptar solo entornos de clave específicos. Por ejemplo, producción puede restringirse solo a claves mk_live_.

Quién puede gestionar claves API

Rol	Crear claves `read-only` / `read-write`	Crear claves `admin`	Rotar/Revocar claves `admin`
owner	Sí	Sí	Sí
admin	Sí	No	No
member	No	No	No

Crear una clave API

Abra la app Mapalyze: Settings > Integrations > API Keys
Haga clic en Create API Key
Introduzca un nombre (por ejemplo: Production backend)
Seleccione el alcance: Read-Only, Read-Write o Admin
Elija el entorno: Live o Test
Cree y copie la clave completa inmediatamente (se muestra una sola vez)

Enviar la clave

Use X-API-Key en cada solicitud:

curl -H "X-API-Key: mk_live_your_key_here" \
  https://<project-ref>.supabase.co/functions/v1/api-gateway/v1/records

También puede enviar la clave como token bearer:

curl -H "Authorization: Bearer mk_live_your_key_here" \
  https://<project-ref>.supabase.co/functions/v1/api-gateway/v1/records

Alcances

Alcance	Permisos
read-only	Endpoints de lectura (`GET`) incluyendo registros, formularios, proyectos, adjuntos, exportaciones, lecturas OGC
read-write	Todo en read-only, más escrituras (`POST`, `PUT`, `PATCH`, `DELETE`)
admin	Todo en read-write, más endpoints de administración (webhooks, métricas API, alertas de abuso/ciclo de vida)

Los alcances son jerárquicos: admin incluye read-write, y read-write incluye read-only.

Idempotencia para escrituras seguras

Para rutas de escritura que usan POST/PUT, envíe Idempotency-Key para que los reintentos no creen duplicados:

curl -X POST \
  -H "X-API-Key: mk_live_..." \
  -H "Idempotency-Key: create-record-20260220-001" \
  -H "Content-Type: application/json" \
  -d '{"form_id":"...","properties":{"name":"Test"}}' \
  "https://<ref>.supabase.co/functions/v1/api-gateway/v1/records"

Vea detalles en Crear, Actualizar y Eliminar.

Mejores prácticas de seguridad

Nunca exponga claves API en código de navegador o cliente móvil.
Almacene las claves en variables de entorno o gestores de secretos.
Use el alcance mínimo necesario.
Rote las claves regularmente y revoque las no utilizadas.
Mantenga separadas las claves de producción y prueba.
Añada sus dominios backend a los orígenes permitidos si usa integraciones basadas en navegador.

Revocar una clave

Desde Settings > Integrations > API Keys, haga clic en Revoke en la clave objetivo. La revocación es inmediata y las solicitudes posteriores devuelven 401.