Get OTP issue status
GET /v1/status
GET https://api.k-otp.dev/v1/statusOverview
Returns verification state, delivery state, and the computed overallStatus for one issue owned by the authenticated app. overallStatus equals verificationStatus unless it is issued; while issued it is derived from deliveryStatus (delivered -> delivered, failed -> delivery_failed, queued/sent -> in_progress, unknown -> pending_lookup).
Immediately after POST /issue the issue row may still be persisting asynchronously; for up to 60 seconds such an issue is reported as pending_lookup instead of 404. The phone number is never returned.
Requires an sk_ secret key; pk_ public keys are rejected with 403.
Authentication
| Accepted keys | Required scope | Also accepted |
|---|---|---|
sk_ | otp:status | otp:read, * |
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
issueId | query | string | yes | issueId returned by POST /v1/issue. |
Response (200)
Current status of the issue.
| Field | Type | Required | Description |
|---|---|---|---|
issueId | string | yes | |
messageId | string | yes | Identifier of the outbound message used for delivery tracking. |
purpose | string | yes | |
templateId | string | yes | |
verificationStatus | "expired" | "issued" | "max_attempts" | "replaced" | "verified" | yes | |
deliveryStatus | "delivered" | "failed" | "queued" | "sent" | "unknown" | yes | |
overallStatus | "delivered" | "delivery_failed" | "expired" | "in_progress" | "max_attempts" | "pending_lookup" | "replaced" | "verified" | yes | verificationStatus unless it is issued; otherwise derived from deliveryStatus for user-facing display. |
providerOutcomeAmbiguous | boolean | true when the provider outcome of the send is unknown (for example a provider timeout). Such sends are never retried automatically. | |
providerOutcomeCode | string | Provider result code, when available. | |
expiresAt | string | yes | RFC 3339 timestamp. |
verifiedAt | string | RFC 3339 timestamp, present once verified. | |
attemptsUsed | number | yes | |
maxAttempts | number | yes | |
attemptsRemaining | number | yes | |
createdAt | string | yes | RFC 3339 timestamp. |
updatedAt | string | yes | RFC 3339 timestamp. |
Error responses
Every error uses the { defined, code, status, message, data? } envelope. See Errors.
| Status | code | Description |
|---|---|---|
| 400 | BAD_REQUEST | issueId is missing or blank. |
| 401 | UNAUTHORIZED | the Authorization: Bearer credential is missing, malformed, inactive, or rejected by introspection. |
| 403 | FORBIDDEN | the credential lacks otp:status (or an accepted alias), or a pk_ public key was used. Public keys are limited to issue/verify. |
| 404 | NOT_FOUND | no issue with this issueId exists for the authenticated app (issues of other apps are indistinguishable from missing ones). |
| 409 | CONFLICT | the request conflicts with the current state of the resource. |
| 500 | INTERNAL_SERVER_ERROR | unexpected server failure. Undefined errors (defined: false) use the same envelope. |
| 503 | SERVICE_UNAVAILABLE | credential introspection or a downstream dependency is temporarily unavailable. Retry with backoff. |
Example request
curl "https://api.k-otp.dev/v1/status?issueId=0192f3c4-8b7a-7c3e-9a51-2f4d6e8b1a90" \
-H "Authorization: Bearer $KOTP_SECRET_KEY"