Issue OTP and queue outbound delivery

POST https://api.k-otp.dev/v1/issue

Overview

Generates a 6-digit OTP, applies quota admission, records the issue, and queues delivery by KakaoTalk AlimTalk with an automatic SMS fallback when AlimTalk delivery fails. The plaintext code is never returned; only issueId, expiry, and attempt metadata are.

SMS fallback. The SMS fallback is on by default (omitted or smsFallback: true): when AlimTalk delivery fails, the same OTP text is sent by SMS at no extra charge. Set smsFallback: false for AlimTalk only: a failed AlimTalk delivery is then not re-sent by SMS, and the price stays the AlimTalk price. An explicit false is part of the idempotency fingerprint (omitted and true are the same request).

Delivery channel. An issue is always delivered by KakaoTalk AlimTalk; channel accepts only alimtalk (also the default). Direct SMS was removed: channel: "sms" is 400 CHANNEL_NOT_SUPPORTED. A template without an approved AlimTalk code cannot be issued (400 TEMPLATE_NOT_AVAILABLE; channelSupport of GET /v1/templates is empty for it). SMS remains only as the automatic fallback of a failed AlimTalk delivery, and the channel of GET /v1/issues items (and delivery records) still reports sms as the delivered channel after a fallback; GET /v1/status has no channel field. Service name. If your app has an approved service name, the message reads [K-OTP] <service name> 인증번호는 ... instead of [K-OTP] 인증번호는 .... You keep passing the same templateId; the named text is used once its AlimTalk template is approved and otherwise the plain text is sent. The name is a property of your app (set in the console, never a request field) and a change applies within about a minute.

Idempotency. An idempotency key is required, either in the Idempotency-Key header or the body idempotencyKey field (both must match when both are sent). A retry with the same key and payload returns the original response without re-sending or re-debiting. When the outcome of the first attempt is unknown (timeout, 503), retry only with the same key.

Replacement. Issuing again for the same phone number and purpose (with a new key) marks the previous issued OTP as replaced. Phone numbers are compared in canonical form: a Korean mobile number is the same number in any spelling (010-1234-5678, 01012345678, +82 10 1234 5678); other numbers are compared by their digits only (+1 415-555-2671 = 14155552671).

Removed options. webOtp (WebOTP needed a direct SMS) is no longer supported: a request that sets it to anything but false is 400 WEB_OTP_NOT_SUPPORTED; the response no longer carries webOtp.

Billing. Credit is reserved at admission and finalized asynchronously after send processing; the response does not include balance or debit amounts. The charged amount is decided server-side per delivery channel (the SMS fallback is included in the AlimTalk price); the deprecated cost field is ignored for billing for every key type. Quota rejection returns 402 with data.code.

Accepts pk_ public keys (browser, Origin must exactly match an allowed origin) or sk_ secret keys.

Test mode. A pk_test_/sk_test_ key never sends a message and never uses credits: the issue is simulated and kept for 7 days, separately from live data (idempotency keys, issue ids and rate limits of test and live keys never mix; a live key cannot read a test issue and vice versa). Test keys only accept test phone numbers (anything else is 400 TEST_NUMBER_REQUIRED), and live keys reject them (400 TEST_NUMBER_IN_LIVE_MODE); both codes are the first token of message and are also in data.code. Test numbers: Korean 010-0000-00xx (+82 10-0000-00xx), UK +44 7700 9000xx and US +1 NXX 555-01xx; the last two digits xx pick the scenario. Every test issue that is created verifies with the fixed code 000000 (except 05), and responses carry mode: 'test'.

Test keys use a fixed platform rate limit instead of the key policy: perKey 120 requests per minute and perKeyDaily 5,000 requests per day, counted per key and separately for issue, verify and reads (status, issues, balance, credit ledger). New test issues also share daily budgets per organization (perOrgDaily, 10,000 by default) and platform-wide (testModeDaily), reset at 00:00 UTC; an exhausted budget returns 429 with Retry-After.

Rate limits. The key's perKey, perIp and perPhone rules are enforced after validation. For pk_ keys the platform default covers perKey/perIp the key does not set and its perPhone default always applies; perKey/perIp never exceed the platform ceiling. An exceeded rule returns 429 with Retry-After and data.retryAfterMs.

Authentication

Parameters

Request body

Response (200)

OTP issued (or an idempotent replay of an earlier issue with the same key).

Error responses

Every error uses the { defined, code, status, message, data? } envelope. See Errors.

Example request

curl -X POST "https://api.k-otp.dev/v1/issue" \
  -H "Authorization: Bearer $KOTP_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"01012345678","purpose":"login"}'