서버에서 보내기

시크릿 API 키로 백엔드, 스크립트, 연동에서 제출을 생성하세요.

백엔드, 크론 작업, 연동은 브라우저와 같은 엔드포인트로 POST할 수 있습니다. 시크릿 API 키를 추가하면 Ikiform이 여러분이 보낸 POST임을 알 수 있습니다.

시크릿 키 만들기

대시보드에서 API keys를 열고 secret 키를 만드세요.
submissions:write 스코프를 부여하세요. 같은 키로 REST API의 데이터도 읽을 때만 submissions:read와 forms:read를 추가하세요.
키를 복사하세요. ik_sk_로 시작하며 한 번만 표시됩니다. Ikiform은 해시만 저장합니다.

제출 보내기

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})`);

시크릿 키를 쓰면 달라지는 점

검사	키 없음	시크릿 키 사용
허용 도메인	`Origin` 또는 `Referer`와 비교	건너뜀
Ikiform 사람 확인	켜져 있으면 필수	건너뜀
직접 발급한 Turnstile 키	토큰 필수	여전히 토큰 필수
레이트 리밋	방문자 IP와 폼별	서버의 IP 기준으로 여전히 적용
필드 검증과 스팸 점수	실행	실행

다른 워크스페이스의 키, 폐기된 키, submissions:write가 없는 시크릿 키는 403 forbidden을 받습니다. 형식이 잘못된 Authorization 헤더도 무시하지 않고 거부하므로, 오타 때문에 익명 POST로 조용히 바뀌는 일은 없습니다.

서버에서 보낸 POST는 모두 서버의 IP 주소에서 오므로, Ikiform의 방문자별 레이트 리밋이 모든 방문자를 합쳐서 셉니다. Standard 프리셋은 IP와 폼별로 분당 5건을 허용하며, 트래픽이 많은 사이트는 이 한도에 닿을 수 있습니다. 가능하면 브라우저에서 POST하거나, 서버를 거쳐 보내는 폼에는 Relaxed 또는 Custom 레이트 리밋을 고르세요.

퍼블리셔블 키

퍼블리셔블 키(ik_pub_)는 브라우저용입니다. 제출만 할 수 있고, 키에 등록한 도메인에서만 작동합니다. 다른 사이트에서 퍼블리셔블 키로 POST하면 403 origin_not_allowed를 받습니다. 사람 확인이나 폼 자체의 허용 도메인은 건너뛰지 않습니다.

시크릿 키를 브라우저 코드, 모바일 앱, 공개 저장소에 절대 넣지 마세요. 유출되면 대시보드에서 폐기하세요.

재시도

서버는 재시도합니다. 주문 ID처럼 제출하는 대상에 대해 변하지 않는 Idempotency-Key를 보내면, 재시도해도 중복을 만들지 않고 첫 응답을 그대로 돌려줍니다. 멱등성을 참고하세요.