{"openapi":"3.1.0","info":{"title":"Authtext API","version":"1.0.0","description":"Authtext is a one-time-code verification API for Australia and APAC, covering SMS, email, authenticator apps and passkeys, with an MCP server for AI coding agents. Live today: SMS and email. Two calls: send a verification, then check the code. Use an at_test_ key while building: nothing is sent, nothing is billed, the code is always 000000. Every error has a stable type, a fix saying what to do next, a docs_url and a request_id."},"servers":[{"url":"https://api.authtext.com.au"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API key: at_live_..., at_test_... or at_agent_..."}},"schemas":{"VerificationCreated":{"type":"object","properties":{"id":{"type":"string","description":"Verification id.","example":"ver_01JD3X9K2M7Q8R5T6V1W0XYZAB"},"status":{"type":"string","enum":["pending"]},"channel":{"type":"string","enum":["sms","email"]},"to":{"type":"string","description":"The destination, masked. A mobile shows the country code and last four digits; an email shows the first character and the domain.","example":"+61*****5678"},"expires_at":{"type":"string","format":"date-time","example":"2026-11-20T00:10:00.000Z"},"attempts_remaining":{"type":"integer","example":5}},"required":["id","status","channel","to","expires_at","attempts_remaining"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request","invalid_api_key","insufficient_scope","destination_not_allowed","account_suspended","live_scope_required","not_found","already_completed","idempotency_conflict","rate_limited","daily_cap_reached","internal_error","delivery_unavailable"],"description":"Stable identifier. Safe to branch on.","example":"rate_limited"},"message":{"type":"string","example":"Too many verifications for this destination. Try again in 42 seconds."},"fix":{"type":"string","description":"One sentence saying what to do next.","example":"Wait for the number of seconds in retry_after before sending again."},"docs_url":{"type":"string","example":"https://authtext.com.au/docs/errors/rate_limited.md"},"request_id":{"type":"string","example":"req_01JD3XA7Q2M7Q8R5T6V1W0XYZA"},"retry_after":{"type":"integer","description":"Seconds to wait. Present on rate limits.","example":42}},"required":["type","message","fix","docs_url","request_id"]}},"required":["error"]},"SendVerificationRequest":{"type":"object","properties":{"to":{"type":"string","minLength":1,"maxLength":254,"description":"Where to send the code: a mobile number in E.164 format for sms, or an email address for email. In test mode, magic destinations simulate outcomes. Numbers: +61400000001 delivered, +61400000002 delivery_failed, +61400000003 rate_limited, +61400000004 expired. Emails: delivered@authtext.test delivered, failed@authtext.test delivery_failed, ratelimited@authtext.test rate_limited, expired@authtext.test expired.","example":"+61412345678"},"channel":{"type":"string","enum":["sms","email"],"description":"How the code is delivered.","example":"sms"},"locale":{"type":"string","enum":["en"],"description":"Message language. Default en.","example":"en"},"reference":{"type":"string","maxLength":255,"description":"Your own identifier for this user or attempt. Returned in webhooks and when you fetch the verification.","example":"user_8841"},"live":{"type":"boolean","description":"Set true to insist on a real message. If the key is in test mode the request fails with live_scope_required instead of quietly simulating. Leave it out to use whatever mode the key has.","example":false}},"required":["to","channel"]},"CheckResult":{"type":"object","properties":{"id":{"type":"string","description":"Verification id.","example":"ver_01JD3X9K2M7Q8R5T6V1W0XYZAB"},"status":{"type":"string","enum":["approved","denied","max_attempts","expired","canceled"],"description":"approved: the code is right. denied: wrong code, attempts remain. max_attempts: too many wrong codes. expired: the code timed out. canceled: the verification was canceled.","example":"approved"},"attempts_remaining":{"type":"integer","example":0}},"required":["id","status","attempts_remaining"]},"CheckVerificationRequest":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":32,"description":"The code the user typed. In test mode the code is always 000000.","example":"482913"}},"required":["code"]},"Verification":{"type":"object","properties":{"id":{"type":"string","description":"Verification id.","example":"ver_01JD3X9K2M7Q8R5T6V1W0XYZAB"},"status":{"type":"string","enum":["pending","approved","max_attempts","expired","canceled"]},"channel":{"type":"string","enum":["sms","email"]},"to":{"type":"string","description":"The destination, masked. A mobile shows the country code and last four digits; an email shows the first character and the domain.","example":"+61*****5678"},"delivery":{"type":"string","enum":["queued","sent","delivered","failed","simulated"],"description":"Where the message stands. queued: waiting to be sent. sent: handed to the provider. delivered: the provider confirmed delivery. failed: it could not be delivered. simulated: test mode, nothing was sent.","example":"sent"},"attempts_remaining":{"type":"integer"},"reference":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time","example":"2026-11-20T00:10:00.000Z"},"expires_at":{"type":"string","format":"date-time","example":"2026-11-20T00:10:00.000Z"},"completed_at":{"type":["string","null"],"format":"date-time","example":"2026-11-20T00:10:00.000Z"}},"required":["id","status","channel","to","delivery","attempts_remaining","reference","created_at","expires_at","completed_at"]}},"parameters":{}},"paths":{"/v1/verifications":{"post":{"operationId":"sendVerification","summary":"Send a verification","description":"Sends a one-time code by SMS or email. Then call the check endpoint with the code the user typed. With a test key, or an agent key without the live scope, nothing is sent, nothing is billed and the code is always 000000. Live sends are limited to 5 per destination an hour, one every 30 seconds per destination, and Australian mobile numbers unless the account has other countries enabled. Needs the verify:write scope.","tags":["Verifications"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","maxLength":255,"description":"The Idempotency-Key header (header names are not case-sensitive). A repeat with the same key within 24 hours returns the original response and sends nothing.","example":"signup-8841-attempt-1"},"required":false,"description":"The Idempotency-Key header (header names are not case-sensitive). A repeat with the same key within 24 hours returns the original response and sends nothing.","in":"header","name":"idempotency-key"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendVerificationRequest"}}}},"responses":{"201":{"description":"The verification was created and the code is on its way.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationCreated"}}}},"400":{"description":"invalid_request: a field is missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_api_key: the key is missing, wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, destination_not_allowed, account_suspended or live_scope_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_conflict: the Idempotency-Key was used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or daily_cap_reached. retry_after says how long to wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error: something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"delivery_unavailable: no message provider is available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/verifications/{id}/check":{"post":{"operationId":"checkVerification","summary":"Check a verification","description":"Checks the code the user typed. A wrong code is not an HTTP error: it returns 200 with status denied and the attempts left. After 5 wrong codes the status is max_attempts. Only approved is billable. Needs the verify:write scope.","tags":["Verifications"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"ver_01JD3X9K2M7Q8R5T6V1W0XYZAB"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckVerificationRequest"}}}},"responses":{"200":{"description":"The result of the check.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckResult"}}}},"400":{"description":"invalid_request: a field is missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_api_key: the key is missing, wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, destination_not_allowed, account_suspended or live_scope_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: no verification with that id in this account and mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"already_completed: the verification was already approved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error: something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/verifications/{id}":{"get":{"operationId":"getVerification","summary":"Get a verification","description":"Returns the current status and delivery state. Never returns the code or the full destination. Needs the verify:read scope.","tags":["Verifications"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"ver_01JD3X9K2M7Q8R5T6V1W0XYZAB"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The verification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verification"}}}},"400":{"description":"invalid_request: a field is missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_api_key: the key is missing, wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, destination_not_allowed, account_suspended or live_scope_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: no verification with that id in this account and mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error: something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/verifications/{id}/resend":{"post":{"operationId":"resendVerification","summary":"Resend a verification","description":"Sends the same code again, for a user who did not receive it. The expiry and the attempts left do not change. Allowed once every 30 seconds per destination. In test mode nothing is sent. Needs the verify:write scope.","tags":["Verifications"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"ver_01JD3X9K2M7Q8R5T6V1W0XYZAB"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The code is on its way again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verification"}}}},"400":{"description":"invalid_request: a field is missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_api_key: the key is missing, wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, destination_not_allowed, account_suspended or live_scope_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: no verification with that id in this account and mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"already_completed: the verification is no longer pending.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: resent too soon. retry_after says how long to wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error: something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"delivery_unavailable: no message provider is available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/verifications/{id}/cancel":{"post":{"operationId":"cancelVerification","summary":"Cancel a verification","description":"Cancels a pending verification so its code can no longer be used. Nothing is billed. Needs the verify:write scope.","tags":["Verifications"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"ver_01JD3X9K2M7Q8R5T6V1W0XYZAB"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The verification is canceled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verification"}}}},"400":{"description":"invalid_request: a field is missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_api_key: the key is missing, wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, destination_not_allowed, account_suspended or live_scope_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: no verification with that id in this account and mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"already_completed: the verification is no longer pending.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error: something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}