Test mode

Test keys let you build and test an integration without sending a real SMS or spending credits. A test key calls the same API with the same request and response shapes, but it only accepts magic test numbers, and the API simulates delivery and verification for them. Nothing is sent, nothing is billed, and the results are deterministic, so you can run them in CI.

Test keys

Create test keys in the console: open an app, go to API keys, switch to the Test tab and choose New test key.

• The API decides the mode from the key prefix. Every issue, verify, status, issues and balance response carries mode: "live" or mode: "test".
• Live and test data are separate. A live key cannot read a test issueId (and the other way round): it answers 404 NOT_FOUND. Idempotency keys are separate too, so reusing one across modes never conflicts.
• A pk_test_ key accepts http:// and https:// origins on localhost and 127.0.0.1 with any port without registering them, so local development works out of the box. Other origins (for example a preview deployment) must be registered exactly, like for a live pk_ key. [::1] and other private addresses are not included.
• Test keys cannot have a custom rate limit. A request over a limit returns 429 TOO_MANY_REQUESTS like a live key, with data.policy: "platform" and data.limit naming the rule: perKey (per minute) or perKeyDaily (per day). Reads (GET /v1/status, /v1/issues, /v1/balance, /v1/credit-ledger) count too, for test keys only.
• New test issues also share daily budgets that reset at 00:00 UTC: 10,000 per organization (data.limit: "perOrgDaily") and a platform-wide budget for all test traffic (data.limit: "testModeDaily"). They are generous on purpose: they only stop runaway loops, such as a test suite stuck retrying. Only new test issues count: an idempotent retry with the same key does not.
• Store a sk_test_ key as a secret, like a live key (for example as a CI secret). Revoke a test key the same way as a live key.

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

Magic test numbers

The last two digits (xx) choose the scenario. Every region uses the same table.

Numbers are compared after removing everything but digits (+82 10… counts as 010…), so hyphens and spaces do not matter.

Scenarios

• Scenario 10 only fails over for AlimTalk delivery (the default channel): with smsFallback: false the delivery is failed after 3 s, and with channel: "sms" it behaves like 00.
• Error responses use the same envelope and fields as live errors (see Errors), so your error handling is exercised as is.
• Re-issuing for the same number and purpose replaces the earlier issue (replaced), and idempotency keys behave as in live mode.
• Templates are rendered exactly as in live mode, so an unknown template or missing variables still return 400 BAD_REQUEST.

The fixed code

Every magic number is verified with a fixed code: 000000 (a 0 for every digit of the code). Test issues have no random code and the code is never returned by the API, just like in live mode.

curl "https://api.k-otp.dev/v1/verify" \
  -H "Authorization: Bearer $KOTP_TEST_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "issueId": "<issueId from the issue response>", "code": "000000" }'

Errors only test mode returns

Both show up on the first request, so a test key deployed to production (or a magic number left in live code) is caught before anyone waits for an SMS.

Balance and credit ledger

Test keys never read your real wallet.

• GET /v1/balance returns a fixed simulated balance that test issues never reduce. Use scenarios 07 and 08 to test the out-of-credit paths.

  {
  	"appId": "app_...",
  	"walletId": "test:app_...",
  	"walletScope": "test",
  	"organizationId": "...",
  	"balance": 1000000,
  	"currency": "CREDIT",
  	"updatedAt": "2026-10-11T03:00:00.000Z",
  	"promoBalance": 0,
  	"promoNextExpiry": null,
  	"mode": "test"
  }

• GET /v1/credit-ledger returns an empty list (items: [], no next cursor).

Test inbox

Each app has a Test inbox in the console (open the app, then Test inbox). It lists the app's test issues of the last 7 days with the time, magic number, scenario, delivery and verification status, attempts and the fixed code, and it has the magic number table with copy buttons. The inbox is usually about a minute behind the API, and up to 15 minutes while the app is busy; for real-time status call GET /v1/status with your test key.

Recommendations

Verify production with live sends

The simulator follows the scenarios above, but it cannot reproduce everything a real carrier or messaging provider does. Before you launch, and after changing templates or channels, send a few OTPs with a live key to real phones you own and check delivery and verification end to end. Those sends use credits like any live send.