v1

Authentication

API Keys

Mapalyze uses organization-scoped API keys for server-to-server integrations.

Key formats

  • mk_live_...: production key.
  • mk_test_...: sandbox/test key.

Your gateway can be configured to accept only specific key environments. For example, production can be restricted to mk_live_ keys only.

Who can manage API keys

Role Create read-only / read-write keys Create admin keys Rotate/Revoke admin keys
owner Yes Yes Yes
admin Yes No No
member No No No

Creating an API key

  1. Open the Mapalyze app: Settings > Integrations > API Keys
  2. Click Create API Key
  3. Enter a name (for example: Production backend)
  4. Select scope: Read-Only, Read-Write, or Admin
  5. Choose environment: Live or Test
  6. Create and copy the full key immediately (shown once)

Sending the key

Use X-API-Key on every request:

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

You can also send the key as bearer token:

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

Scopes

Scope Permissions
read-only Read endpoints (GET) including records, forms, projects, attachments, exports, OGC reads
read-write Everything in read-only, plus writes (POST, PUT, PATCH, DELETE)
admin Everything in read-write, plus admin endpoints (webhooks, API metrics, abuse/lifecycle alerts)

Scopes are hierarchical: admin includes read-write, and read-write includes read-only.

Idempotency for write safety

For write routes that use POST/PUT, send Idempotency-Key so retries do not create duplicates:

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"

See details in Create, Update & Delete.

Security best practices

  • Never expose API keys in browser/mobile client code.
  • Store keys in environment variables or secret managers.
  • Use the minimum scope required.
  • Rotate keys regularly and revoke unused keys.
  • Keep production and test keys separate.
  • Add your backend domains to allowed origins if you use browser-based integrations.

Revoking a key

From Settings > Integrations > API Keys, click Revoke on the target key. Revocation is immediate and further requests return 401.

¿Necesita ayuda con la API? Contacte a nuestro equipo de soporte.

Comience Gratis