Autenticacao | Documentação da API Mapalyze

Autenticacao

Chaves API

O Mapalyze usa chaves API com escopo de organização para integrações servidor a servidor.

Formatos de chave

mk_live_...: chave de produção.
mk_test_...: chave de sandbox/teste.

Seu gateway pode ser configurado para aceitar apenas ambientes de chave específicos. Por exemplo, produção pode ser restrita apenas a chaves mk_live_.

Quem pode gerenciar chaves API

Função	Criar chaves `read-only` / `read-write`	Criar chaves `admin`	Rotacionar/Revogar chaves `admin`
owner	Sim	Sim	Sim
admin	Sim	Não	Não
member	Não	Não	Não

Criar uma chave API

Abra o app Mapalyze: Settings > Integrations > API Keys
Clique em Create API Key
Digite um nome (por exemplo: Production backend)
Selecione o escopo: Read-Only, Read-Write ou Admin
Escolha o ambiente: Live ou Test
Crie e copie a chave completa imediatamente (exibida apenas uma vez)

Enviar a chave

Use X-API-Key em cada requisição:

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

Você também pode enviar a chave como token bearer:

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

Escopos

Escopo	Permissões
read-only	Endpoints de leitura (`GET`) incluindo registros, formulários, projetos, anexos, exportações, leituras OGC
read-write	Tudo em read-only, mais escritas (`POST`, `PUT`, `PATCH`, `DELETE`)
admin	Tudo em read-write, mais endpoints de administração (webhooks, métricas API, alertas de abuso/ciclo de vida)

Os escopos são hierárquicos: admin inclui read-write, e read-write inclui read-only.

Idempotência para escritas seguras

Para rotas de escrita usando POST/PUT, envie Idempotency-Key para que retentativas não criem duplicatas:

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"

Veja detalhes em Criar, Atualizar e Excluir.

Melhores práticas de segurança

Nunca exponha chaves API em código de navegador ou cliente móvel.
Armazene chaves em variáveis de ambiente ou gerenciadores de segredos.
Use o escopo mínimo necessário.
Rotacione chaves regularmente e revogue chaves não utilizadas.
Mantenha chaves de produção e teste separadas.
Adicione seus domínios backend às origens permitidas se usar integrações baseadas em navegador.

Revogar uma chave

Em Settings > Integrations > API Keys, clique em Revoke na chave alvo. A revogação é imediata e requisições posteriores retornam 401.