A partir de um servidor

Crie envios a partir de um backend, script ou integração com uma chave de API secreta.

Backends, cron jobs e integrações podem enviar para o mesmo endpoint que os navegadores. Adicione uma chave de API secreta para o Ikiform saber que o envio é seu.

Crie uma chave secreta

No painel, abra API keys e crie uma chave secret.
Dê a ela o escopo submissions:write. Adicione submissions:read e forms:read só se a mesma chave também for ler dados da API REST.
Copie a chave. Ela começa com ik_sk_ e é exibida uma única vez; o Ikiform guarda só o hash dela.

Faça um envio

submit.ts

const response = await fetch("https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.IKIFORM_SECRET_KEY}`,
    "Idempotency-Key": order.id,
  },
  body: JSON.stringify({ email: order.email, plan: order.plan }),
});

const result = await response.json();
if (!result.ok) throw new Error(`${result.error.code}: ${result.error.message} (${result.request_id})`);

O que uma chave secreta muda

Verificação	Sem chave	Com chave secreta
Domínios permitidos	Comparados com `Origin` ou `Referer`	Ignorada
Verificação humana do Ikiform	Obrigatória quando ativada	Ignorada
Suas próprias chaves do Turnstile	Token obrigatório	Token continua obrigatório
Limites de taxa	Por IP de visitante e formulário	Continuam valendo, pelo IP do seu servidor
Validação de campos e pontuação de spam	Rodam	Rodam

Uma chave de outro workspace, uma chave revogada ou uma chave secreta sem submissions:write recebe 403 forbidden. Um header Authorization malformado também é recusado em vez de ignorado, então um erro de digitação nunca vira silenciosamente um envio anônimo.

Envios feitos pelo seu servidor vêm todos do endereço IP do seu servidor, então os limites de taxa por visitante do Ikiform contam todos os visitantes juntos. O preset Standard permite 5 envios por minuto por IP e formulário, o que um site movimentado pode atingir. Envie do navegador quando puder, ou escolha o limite de taxa Relaxed ou Custom para formulários que passam por um servidor.

Chaves publicáveis

Chaves publicáveis (ik_pub_) são para navegadores. Elas só podem enviar, e só a partir dos domínios que você lista na chave. Um envio com chave publicável vindo de qualquer outro site recebe 403 origin_not_allowed. Elas não pulam a verificação humana nem os domínios permitidos do próprio formulário.

Nunca coloque uma chave secreta em código de navegador, em um app mobile ou em um repositório público. Revogue-a no painel se ela vazar.

Novas tentativas

Servidores tentam de novo. Envie um Idempotency-Key estável para o que você está enviando, como o id de um pedido, e uma nova tentativa vai repetir a primeira resposta em vez de criar um duplicado. Veja Idempotência.