Skip to content
Akedly
Command reference

OTP

Akedly CLI command reference: OTP.

Build with AI agents

otp v1 create

Open the V1 delivery flow by creating its short-lived pending transaction; creation itself sends nothing.

When to use

  • Before a test send, create against a known owned active OTP pipeline and use its matching test/dev-mode configuration.

How it works

  1. POST creates a pending record containing the pipeline, destination, and resolved API key in the body. It expires for activation after two minutes.

Prerequisites

  • An active owned OTP delivery pipeline and an API key available to the CLI; this only creates the pending V1 record.

Expected outcome

A pending transaction ID is returned; no message has been sent yet.

Next steps

  • Use data.transactionID immediately with otp v1 activate --yes; if it expired, start a fresh create.

Usage

sh
akedly otp v1 create

Inspect this command offline before preparing an operation:

sh
akedly describe "otp v1 create" --output json

Flags

FlagTypeEnum / rangeRequiredDescription
--ksaboolean switch—noSelect the KSA deployment.
--pipeline-idid—yesCommand-specific option; see the full command details below. Manifest body field: pipelineID.
--phone-numbertext—yesCommand-specific option; see the full command details below. Manifest body field: verificationAddress.phoneNumber.
--api-keytext—noSelect a saved API key by its eight-character prefix; never supply a full Secret. Manifest body field: APIKey.
--dry-runboolean switch—noPreview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--helpboolean switch—noShow offline command help.
--outputenumjson | humannoSelect JSON or human output.
--fieldsdot-paths—noSelect comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: api-key. Permission: none declared.

Server request: POST /transactions.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

write: Non-idempotent writes are not automatically retried. guarded-write: when an update carries the revision read from the server, its write is not automatically retried after network errors or HTTP 429/502/503/504. It may already be saved; inspect the resource before rerunning. A rerun reads current settings again. The explicit CLI_RATE_LIMITED refusal exception below still applies. recommendation-read: the recommendation request made while planning --recommended-limits is not automatically retried after network errors or HTTP 429/502/503/504. If planning fails, no update is sent; rerun the command to request a new recommendation. The explicit CLI_RATE_LIMITED refusal exception below still applies. This label does not change the retry policy of the standalone rate-recommendations command.

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Create a pending V1 transaction; nothing is sent until activate within 2 minutes. Uses an API key in the body. If the result is lost, create again.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic offline fixture

Open the V1 delivery flow by creating its short-lived pending transaction; creation itself sends nothing.

sh
akedly otp v1 create --pipeline-id 65a1b2c3d4e5f67890123457 --phone-number +201234567890

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "transactionID": "9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f",
    "otpLanguage": "en"
  }
}

All IDs, destination, company, dates, callback URL and payload values are synthetic fixtures; example.invalid is reserved for documentation. Do not paste a real OTP, phone, API key, widget Secret, token, or account identifier into an agent test or shared output.

This worked response is illustrative only and was not executed against an account.

Additional command forms

sh
akedly otp v1 create --pipeline-id <id> --phone-number <number>

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

Successful response example is synthetic and demonstrates observed field names/types; server-supplied extension fields are preserved.

Responses can contain personal data and, on some transaction paths, live OTP-related values. Treat actual output as secret; examples contain only synthetic fixture values.

Own recovery guidance

CodeHint
API_ERRORV1 reports client mistakes such as an unknown API key ('User not found'), an unknown or inactive pipeline, or a quota problem as HTTP 500 with a plain message and no code. Read `message`.

Common error guidance.

otp v1 activate

Dispatch the message for a pending V1 transaction. This is the send boundary and may incur a bill.

When to use

  • Only after a V1 create succeeded and before its two-minute activation window expires; for safe tests use a dev-mode Test Pair.

How it works

  1. POSTs once without credentials to the public activation route; ambiguous transport failures are not replay-safe.

Prerequisites

  • A pending V1 transaction created through this integration (activate), or the request ID returned after activation (verify); public activation/verification requires no CLI Login or API key.

Expected outcome

The activation response supplies data._id, the transaction-request ID needed for verification.

Next steps

  • Deliver/check the synthetic test destination, then verify with otp v1 verify <data._id> --otp <code>. If outcome is unclear, check status/history before retrying.

Usage

sh
akedly otp v1 activate <transactionID>

Inspect this command offline before preparing an operation:

sh
akedly describe "otp v1 activate" --output json
PositionalGrammarUsage guidance
<transactionID>^[a-fA-F0-9]{64}$Required positional argument.

Flags

FlagTypeEnum / rangeRequiredDescription
--ksaboolean switch—noSelect the KSA deployment.
--yesboolean switch—noConfirm this action where consent is required.
--dry-runboolean switch—noPreview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--helpboolean switch—noShow offline command help.
--outputenumjson | humannoSelect JSON or human output.
--fieldsdot-paths—noSelect comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: public. Permission: none declared.

Server request: POST /transactions/activate/:transactionID.

Shared server-guard guidance.

Consent

--yes. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: true.

Retry

write: Non-idempotent writes are not automatically retried. guarded-write: when an update carries the revision read from the server, its write is not automatically retried after network errors or HTTP 429/502/503/504. It may already be saved; inspect the resource before rerunning. A rerun reads current settings again. The explicit CLI_RATE_LIMITED refusal exception below still applies. recommendation-read: the recommendation request made while planning --recommended-limits is not automatically retried after network errors or HTTP 429/502/503/504. If planning fails, no update is sent; rerun the command to request a new recommendation. The explicit CLI_RATE_LIMITED refusal exception below still applies. This label does not change the retry policy of the standalone rate-recommendations command.

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Activate a pending transaction within 2 minutes. Always a real, possibly billed send; requires --yes. No credentials. An ambiguous failure may have sent a message; check the destination before retrying. Use data._id from the response to verify.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic offline fixture

Dispatch the message for a pending V1 transaction. This is the send boundary and may incur a bill.

sh
akedly otp v1 activate 9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f --yes

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "message": "OTP sent",
  "data": {
    "_id": "65a1b2c3d4e5f67890123456"
  }
}

All IDs, destination, company, dates, callback URL and payload values are synthetic fixtures; example.invalid is reserved for documentation. Do not paste a real OTP, phone, API key, widget Secret, token, or account identifier into an agent test or shared output.

This worked response is illustrative only and was not executed against an account.

Additional command forms

sh
akedly otp v1 activate <transactionID> --yes

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

Successful response example is synthetic and demonstrates observed field names/types; server-supplied extension fields are preserved.

Responses can contain personal data and, on some transaction paths, live OTP-related values. Treat actual output as secret; examples contain only synthetic fixture values.

Send/attempt operations are not replay-safe: on an ambiguous result inspect status/history/destination before trying again.

Own recovery guidance

CodeHint
API_ERRORActivate within 2 minutes of `otp v1 create`; otherwise create a new transaction.

Common error guidance.

otp v1 verify

Complete a V1 verification using the ID returned by activation.

When to use

  • After the recipient or dev Test Pair has received a code and the activation response supplied data._id.

How it works

  1. POSTs the supplied OTP to the unauthenticated public verify route; verification may settle usage billing.

Prerequisites

  • A pending V1 transaction created through this integration (activate), or the request ID returned after activation (verify); public activation/verification requires no CLI Login or API key.

Expected outcome

A success envelope reports the transaction request and main transaction; the API may include sensitive live OTP-related fields in other response data.

Next steps

  • Keep the output private; use the returned verification/callback information in your integration.

Usage

sh
akedly otp v1 verify <transactionReqID>

Inspect this command offline before preparing an operation:

sh
akedly describe "otp v1 verify" --output json
PositionalGrammarUsage guidance
<transactionReqID>^[a-fA-F0-9]{24}$Required positional argument.

Flags

FlagTypeEnum / rangeRequiredDescription
--ksaboolean switch—noSelect the KSA deployment.
--otptext—yesCommand-specific option; see the full command details below. Manifest body field: otp.
--dry-runboolean switch—noPreview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--helpboolean switch—noShow offline command help.
--outputenumjson | humannoSelect JSON or human output.
--fieldsdot-paths—noSelect comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: public. Permission: none declared.

Server request: POST /transactions/verify/:id.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

write: Non-idempotent writes are not automatically retried. guarded-write: when an update carries the revision read from the server, its write is not automatically retried after network errors or HTTP 429/502/503/504. It may already be saved; inspect the resource before rerunning. A rerun reads current settings again. The explicit CLI_RATE_LIMITED refusal exception below still applies. recommendation-read: the recommendation request made while planning --recommended-limits is not automatically retried after network errors or HTTP 429/502/503/504. If planning fails, no update is sent; rerun the command to request a new recommendation. The explicit CLI_RATE_LIMITED refusal exception below still applies. This label does not change the retry policy of the standalone rate-recommendations command.

Output

Sensitive output: live-otp. Responses may contain live OTP fields; keep them private.

Full command details

Verify a V1 OTP without credentials, using data._id from activate. Responses may include live OTP fields; keep output private.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic offline fixture

Complete a V1 verification using the ID returned by activation.

sh
akedly otp v1 verify 65a1b2c3d4e5f67890123456 --otp 123456

Illustrative response (sensitive values omitted):

json
{
  "message": "OTP verified successfully",
  "status": "success",
  "data": {
    "frontendCallbackURL": "https://example.invalid/verified",
    "mainTransaction": {
      "transactionID": "9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f",
      "status": "Successful"
    },
    "transactionReq": {
      "_id": "65a1b2c3d4e5f67890123456",
      "status": "Successful",
      "verified": true,
      "billingAmount": 0.25,
      "billed": true
    }
  }
}

All IDs, destination, company, dates, callback URL and payload values are synthetic fixtures; example.invalid is reserved for documentation. Do not paste a real OTP, phone, API key, widget Secret, token, or account identifier into an agent test or shared output.

This worked response is illustrative only and was not executed against an account.

Additional command forms

sh
akedly otp v1 verify <transactionReqID> --otp 1234

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

Successful response example is synthetic and demonstrates observed field names/types; server-supplied extension fields are preserved.

Responses can contain personal data and, on some transaction paths, live OTP-related values. Treat actual output as secret; examples contain only synthetic fixture values.

Own recovery guidance

CodeHint
API_ERRORV1 verification errors carry no code. `Invalid OTP`: re-enter the code (10 attempts). Expired or already verified: create a new transaction with akedly otp v1 create.

Common error guidance.

otp v1.2 challenge

Inspect or obtain a fresh proof-of-work challenge for a V1.2 pipeline without sending an OTP.

When to use

  • When troubleshooting challenge policy or preparing a manual protocol integration for an owned pipeline.

How it works

  1. Authenticated API-key GET resolves the key and passes pipelineID as a query parameter; it is a read and safe to retry.

Prerequisites

  • An owned V1.2 OTP delivery pipeline and a configured API key. Use a dev-mode Test Pair for safe sends; the challenge command itself does not send.

Expected outcome

Returns the server challenge requirements and expiry for that pipeline.

Next steps

  • For CLI-managed sends, prefer otp v1.2 send so challenge acquisition and solving are paired with a single send.

Usage

sh
akedly otp v1.2 challenge

Inspect this command offline before preparing an operation:

sh
akedly describe "otp v1.2 challenge" --output json

Flags

FlagTypeEnum / rangeRequiredDescription
--ksaboolean switch—noSelect the KSA deployment.
--pipeline-idid—yesCommand-specific option; see the full command details below. Query parameter: pipelineID.
--api-keytext—noSelect a saved API key by its eight-character prefix; never supply a full Secret.
--helpboolean switch—noShow offline command help.
--outputenumjson | humannoSelect JSON or human output.
--fieldsdot-paths—noSelect comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: api-key. Permission: none declared.

Server request: GET /api/v1.2/transactions/challenge.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

idempotent: Idempotent requests retry network errors and HTTP 429/502/503/504, at most 3 tries, waiting for cooldownSeconds, retryAfter or the Retry-After header (otherwise 1 second) between tries, up to 30 seconds; a longer requested wait is returned as the error.

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Fetch a fresh V1.2 PoW challenge using AKEDLY_API_KEY or a saved API key selected with --api-key <prefix>; CLI Logins are not used.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic offline fixture

Inspect or obtain a fresh proof-of-work challenge for a V1.2 pipeline without sending an OTP.

sh
akedly otp v1.2 challenge --pipeline-id 65a1b2c3d4e5f67890123457

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "challengeRequired": true,
    "challengeToken": "synthetic-challenge-token",
    "challenge": "synthetic-pow-challenge",
    "difficulty": 1,
    "expiresAt": "2026-10-29T12:01:00.000Z",
    "algorithm": "sha256",
    "instructions": "Find nonce where SHA256(challenge + ':' + nonce) starts with <difficulty> zeros",
    "turnstile": {
      "required": false,
      "siteKey": null
    }
  }
}

All IDs, destination, company, dates, callback URL and payload values are synthetic fixtures; example.invalid is reserved for documentation. Do not paste a real OTP, phone, API key, widget Secret, token, or account identifier into an agent test or shared output.

This worked response is illustrative only and was not executed against an account.

Additional command forms

sh
akedly otp v1.2 challenge --pipeline-id <id>

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

Successful response example is synthetic and demonstrates observed field names/types; server-supplied extension fields are preserved.

Responses can contain personal data and, on some transaction paths, live OTP-related values. Treat actual output as secret; examples contain only synthetic fixture values.

Successful challenge responses have three shapes: normal PoW includes the challenge fields; bypass/disabled PoW omits them. Turnstile may independently be required and its siteKey may be a string or null.

Common error guidance.

otp v1.2 send

Send a V1.2 OTP after the CLI fetches and solves the fresh proof-of-work challenge.

When to use

  • Use with an owned pipeline configured for safe testing (dev-mode Test Pair, or Turnstile settings appropriate to your flow); this is an actual potentially billable send.

How it works

  1. CLI fetches a challenge, solves PoW locally, then POSTs once with API key, pipeline, phone, and optional Turnstile token.

Prerequisites

  • An owned V1.2 OTP delivery pipeline and a configured API key. Use a dev-mode Test Pair for safe sends; the challenge command itself does not send.

Expected outcome

Returns the send API response and transaction/request identifiers when supplied by the server.

Next steps

  • Check the destination and transaction status; after an ambiguous failure do not blindly resend because a message may already have gone out.

Usage

sh
akedly otp v1.2 send

Inspect this command offline before preparing an operation:

sh
akedly describe "otp v1.2 send" --output json

Flags

FlagTypeEnum / rangeRequiredDescription
--ksaboolean switch—noSelect the KSA deployment.
--pipeline-idid—yesCommand-specific option; see the full command details below. Manifest body field: pipelineID.
--phone-numbertext—yesCommand-specific option; see the full command details below. Manifest body field: verificationAddress.phoneNumber.
--turnstile-tokentext—noCommand-specific option; see the full command details below. Manifest body field: turnstileToken.
--api-keytext—noSelect a saved API key by its eight-character prefix; never supply a full Secret.
--yesboolean switch—noConfirm this action where consent is required.
--dry-runboolean switch—noPreview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--helpboolean switch—noShow offline command help.
--outputenumjson | humannoSelect JSON or human output.
--fieldsdot-paths—noSelect comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: api-key. Permission: none declared.

Server request: POST /api/v1.2/transactions/send.

Shared server-guard guidance.

Consent

--yes. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: true.

Retry

write: Non-idempotent writes are not automatically retried. guarded-write: when an update carries the revision read from the server, its write is not automatically retried after network errors or HTTP 429/502/503/504. It may already be saved; inspect the resource before rerunning. A rerun reads current settings again. The explicit CLI_RATE_LIMITED refusal exception below still applies. recommendation-read: the recommendation request made while planning --recommended-limits is not automatically retried after network errors or HTTP 429/502/503/504. If planning fails, no update is sent; rerun the command to request a new recommendation. The explicit CLI_RATE_LIMITED refusal exception below still applies. This label does not change the retry policy of the standalone rate-recommendations command.

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Fetch and solve a fresh PoW challenge, then send once using AKEDLY_API_KEY or a saved API key selected with --api-key <prefix>; CLI Logins are not used. Requires --yes; real sends can be billed. Prefer dev-mode Test Pairs. Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes. An ambiguous failure may have sent a message; check the destination before retrying. Dry runs resolve the key but send nothing.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic offline fixture

Send a V1.2 OTP after the CLI fetches and solves the fresh proof-of-work challenge.

sh
akedly otp v1.2 send --pipeline-id 65a1b2c3d4e5f67890123457 --phone-number +201234567890 --yes

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "transactionID": "9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f",
    "transactionReqID": "65a1b2c3d4e5f67890123456",
    "channels": [
      "sms"
    ],
    "expiresAt": "2026-10-29T12:05:00.000Z"
  }
}

All IDs, destination, company, dates, callback URL and payload values are synthetic fixtures; example.invalid is reserved for documentation. Do not paste a real OTP, phone, API key, widget Secret, token, or account identifier into an agent test or shared output.

This worked response is illustrative only and was not executed against an account.

Additional command forms

sh
akedly otp v1.2 send --pipeline-id <id> --phone-number <number> --yes

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

Successful response example is synthetic and demonstrates observed field names/types; server-supplied extension fields are preserved.

Responses can contain personal data and, on some transaction paths, live OTP-related values. Treat actual output as secret; examples contain only synthetic fixture values.

Send/attempt operations are not replay-safe: on an ambiguous result inspect status/history/destination before trying again.

Common error guidance.

otp v1.2 verify

Verify a V1.2 OTP against the request identifier produced by the send flow.

When to use

  • After the V1.2 recipient has a code; use a synthetic Test Pair in tests.

How it works

  1. Unauthenticated POST sends the 4–8 digit OTP and request identifier to the versioned verify endpoint.

Prerequisites

  • A pending V1 transaction created through this integration (activate), or the request ID returned after activation (verify); public activation/verification requires no CLI Login or API key.

Expected outcome

Success confirms verification; failures may expose callback details and OTP responses should stay private.

Next steps

  • Use resulting transaction state in the calling application; consult status if result is unclear.

Usage

sh
akedly otp v1.2 verify <transactionReqID>

Inspect this command offline before preparing an operation:

sh
akedly describe "otp v1.2 verify" --output json
PositionalGrammarUsage guidance
<transactionReqID>TextRequired positional argument.

Flags

FlagTypeEnum / rangeRequiredDescription
--ksaboolean switch—noSelect the KSA deployment.
--otptext—yesCommand-specific option; see the full command details below. Manifest body field: otp.
--dry-runboolean switch—noPreview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--helpboolean switch—noShow offline command help.
--outputenumjson | humannoSelect JSON or human output.
--fieldsdot-paths—noSelect comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: public. Permission: none declared.

Server request: POST /api/v1.2/transactions/verify/:transactionReqID.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

write: Non-idempotent writes are not automatically retried. guarded-write: when an update carries the revision read from the server, its write is not automatically retried after network errors or HTTP 429/502/503/504. It may already be saved; inspect the resource before rerunning. A rerun reads current settings again. The explicit CLI_RATE_LIMITED refusal exception below still applies. recommendation-read: the recommendation request made while planning --recommended-limits is not automatically retried after network errors or HTTP 429/502/503/504. If planning fails, no update is sent; rerun the command to request a new recommendation. The explicit CLI_RATE_LIMITED refusal exception below still applies. This label does not change the retry policy of the standalone rate-recommendations command.

Output

Sensitive output: live-otp. Responses may contain live OTP fields; keep them private.

Full command details

Verify a 4–8 digit OTP without credentials. The API response may include live OTP fields; keep output private. Dry runs send nothing.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic offline fixture

Verify a V1.2 OTP against the request identifier produced by the send flow.

sh
akedly otp v1.2 verify 65a1b2c3d4e5f67890123456 --otp 123456

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "message": "OTP verified successfully",
  "data": {
    "verified": true,
    "transactionID": "9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f",
    "frontendCallbackURL": "https://example.invalid/verified",
    "enrollmentToken": "synthetic-enrollment-token"
  }
}

All IDs, destination, company, dates, callback URL and payload values are synthetic fixtures; example.invalid is reserved for documentation. Do not paste a real OTP, phone, API key, widget Secret, token, or account identifier into an agent test or shared output.

This worked response is illustrative only and was not executed against an account.

Additional command forms

sh
akedly otp v1.2 verify <transactionReqID> --otp 123456

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

Successful response example is synthetic and demonstrates observed field names/types; server-supplied extension fields are preserved.

Responses can contain personal data and, on some transaction paths, live OTP-related values. Treat actual output as secret; examples contain only synthetic fixture values.

This V1.2 success DTO is distinct from V1: it returns verified and transactionID with optional callback/token values, not mainTransaction or transactionReq. enrollmentToken is a synthetic example value.

Common error guidance.

otp v2 attempt

Create a browser-based V2 widget attempt for a phone verification.

When to use

  • When an owned widget has a publicKey and its one-time shown Secret is available locally; choose a dev-mode Test Pair before triggering delivery.

How it works

  1. Signs a POST with widget Secret and API key; without --wait returns creation response. With --wait, prints the attempt link to stderr and polls status until verified/terminal/expiry.

Prerequisites

  • An owned widget publicKey and its matching 64-hex widget Secret in a local file or AKEDLY_WIDGET_SECRET, plus API key. Test only with a dev-mode Test Pair; this attempt can trigger a real billed send.

Expected outcome

Creation returns attemptId, iframeUrl and expiresAt; wait mode adds attempt and waited outcome metadata to the status response. OTP-containing API fields are private.

Next steps

  • Open iframeUrl to finish; resume/check with transactions status --attempt-id <attemptId>.

Usage

sh
akedly otp v2 attempt

Inspect this command offline before preparing an operation:

sh
akedly describe "otp v2 attempt" --output json

Flags

FlagTypeEnum / rangeRequiredDescription
--ksaboolean switch—noSelect the KSA deployment.
--public-keytext—yesCommand-specific option; see the full command details below. Manifest body field: publicKey.
--phone-numbertext—yesCommand-specific option; see the full command details below. Manifest body field: verificationAddress.phoneNumber.
--widget-secret-filetext—noCommand-specific option; see the full command details below.
--waitboolean switch—noCommand-specific option; see the full command details below.
--timeoutseconds—noCommand-specific option; see the full command details below.
--api-keytext—noSelect a saved API key by its eight-character prefix; never supply a full Secret. Manifest body field: apiKey.
--yesboolean switch—noConfirm this action where consent is required.
--dry-runboolean switch—noPreview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--helpboolean switch—noShow offline command help.
--outputenumjson | humannoSelect JSON or human output.
--fieldsdot-paths—noSelect comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: api-key. Permission: none declared.

Server request: POST /widget-sdk/create-attempt.

Shared server-guard guidance.

Consent

--yes. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: true.

Retry

write: Non-idempotent writes are not automatically retried. guarded-write: when an update carries the revision read from the server, its write is not automatically retried after network errors or HTTP 429/502/503/504. It may already be saved; inspect the resource before rerunning. A rerun reads current settings again. The explicit CLI_RATE_LIMITED refusal exception below still applies. recommendation-read: the recommendation request made while planning --recommended-limits is not automatically retried after network errors or HTTP 429/502/503/504. If planning fails, no update is sent; rerun the command to request a new recommendation. The explicit CLI_RATE_LIMITED refusal exception below still applies. This label does not change the retry policy of the standalone rate-recommendations command.

Output

Sensitive output: live-otp. Responses may contain live OTP fields; keep them private.

Full command details

Create a V2 attempt signed with the widget Secret from --widget-secret-file or AKEDLY_WIDGET_SECRET (file wins). Requires --yes; opening the link can send a billed OTP. --wait prints the browser link on stderr and polls every 3 seconds until verification or expiry; --timeout caps the wait. Resume with transactions status --attempt-id <attemptId>. All waits share 300 ids/minute per account; retries count again. Responses may contain live OTP fields; keep output private. Use the publicKey from widgets create or widgets get, not the Mongo _id or widgetId. The widget Secret is separate from the API key; --widget-secret-file wins over AKEDLY_WIDGET_SECRET. Open iframeUrl in a browser to complete verification.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic offline fixture

Create a browser-based V2 widget attempt for a phone verification.

sh
akedly otp v2 attempt --public-key pk_0123456789abcdef0123456789abcdef01234567 --phone-number +201234567890 --widget-secret-file ./synthetic-widget-secret.txt --yes

Input file: synthetic-widget-secret.txt (text).

text
[REDACTED — use your privately saved secret file]

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "attemptId": "att_synthetic_01",
    "iframeUrl": "https://auth.example.invalid/a/att_synthetic_01",
    "expiresAt": "2026-10-29T12:05:00.000Z"
  }
}

All IDs, destination, company, dates, callback URL and payload values are synthetic fixtures; example.invalid is reserved for documentation. Do not paste a real OTP, phone, API key, widget Secret, token, or account identifier into an agent test or shared output.

This worked response is illustrative only and was not executed against an account.

The synthetic widget Secret file fixture is private example data; never print it in the human guide or use a real Secret.

Synthetic attempt with browser wait

Create the attempt and wait for browser verification while keeping the creation iframe URL separate from status replay data.

sh
akedly otp v2 attempt --public-key pk_0123456789abcdef0123456789abcdef01234567 --phone-number +201234567890 --widget-secret-file ./synthetic-widget-secret.txt --yes --wait

Input file: synthetic-widget-secret.txt (text).

text
[REDACTED — use your privately saved secret file]

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "status": "success",
    "timestamp": "2026-10-29T12:00:03.000Z",
    "widgetAttempt": {
      "attemptId": "att_synthetic_01",
      "widgetId": "wid_synthetic_01",
      "userId": "65a1b2c3d4e5f67890123458",
      "status": "verified",
      "isTest": true,
      "verificationAddress": {
        "phoneNumber": "+201234567890",
        "email": null
      },
      "otpConfig": {
        "digits": 6,
        "resendCount": 0
      },
      "publicMetadata": {
        "fixture": "synthetic"
      },
      "createdAt": "2026-10-29T12:00:00.000Z",
      "expiresAt": "2026-10-29T12:05:00.000Z",
      "captchaVerifiedAt": "2026-10-29T12:00:00.000Z",
      "otpRequestedAt": "2026-10-29T12:00:00.000Z",
      "completedAt": "2026-10-29T12:00:03.000Z"
    },
    "transaction": {
      "transactionID": "9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f",
      "status": "Successful",
      "verificationAddress": {
        "phoneNumber": "+201234567890"
      },
      "expirationDate": "2026-10-29T12:05:00.000Z",
      "creationDate": "2026-10-29T12:00:00.000Z"
    },
    "transactionReq": {
      "_id": "65a1b2c3d4e5f67890123456",
      "status": "Successful",
      "verified": true,
      "billingAmount": 0.25,
      "billed": true,
      "verificationDate": "2026-10-29T12:00:03.000Z"
    },
    "publicMetadata": {
      "fixture": "synthetic"
    },
    "privateMetadata": {
      "ref": "synthetic"
    }
  },
  "waited": {
    "outcome": "verified",
    "polls": 2,
    "elapsedSeconds": 3.25
  },
  "attempt": {
    "attemptId": "att_synthetic_01",
    "iframeUrl": "https://auth.example.invalid/a/att_synthetic_01",
    "expiresAt": "2026-10-29T12:05:00.000Z"
  }
}

The status replay widgetAttempt contains the safe attempt projection and does not contain iframeUrl. The separate top-level attempt retains the creation URL.

Every identity, destination, URL, Secret and result value is synthetic. Never render the Secret file content in the human guide or execute this example.

Synthetic V2 attempt using a private Secret file

Create a V2 widget attempt for an owned widget, keeping the widget Secret in a local single-line file; the response provides the browser URL and expiry, not a completed verification.

sh
akedly otp v2 attempt --public-key pk_0123456789abcdef0123456789abcdef01234567 --phone-number +201234567890 --widget-secret-file ./synthetic-widget-secret.txt --yes

Input file: synthetic-widget-secret.txt (text).

text
[REDACTED — use your privately saved secret file]

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "attemptId": "att_synthetic_02",
    "iframeUrl": "https://auth.example.invalid/a/att_synthetic_02",
    "expiresAt": "2026-10-30T12:05:00.000Z"
  }
}

The argv is syntactically complete and the file is a regular-text, one-line, 64-character lowercase hexadecimal synthetic widget Secret; the reader trims its trailing newline. The fictional publicKey/Secret pair and resource IDs do not exist in an account, so this is a response-shape fixture and must not be executed.

Actual use requires an owned widget publicKey and its matching Secret, a usable API key, and a safe dev-mode Test Pair configured for that widget/pipeline. --yes is required because opening the returned iframeUrl can trigger a real OTP send and billing.

This example stops at attempt creation. It does not claim the attempt was verified or that an OTP was sent. If someone opens the link, the browser must complete whichever PoW and/or Turnstile checks that widget configuration requires; do not claim those checks were bypassed.

Every identifier, destination, URL and Secret value is synthetic. Do not substitute a real phone, OTP, API key, widget Secret or token in agent examples, logs or shared output. Keep Secret file contents out of rendered human guides. No command or network request was made.

Additional command forms

sh
akedly otp v2 attempt --public-key <publicKey> --phone-number <number> --widget-secret-file <path> --yes --wait

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

Successful response example is synthetic and demonstrates observed field names/types; server-supplied extension fields are preserved.

Responses can contain personal data and, on some transaction paths, live OTP-related values. Treat actual output as secret; examples contain only synthetic fixture values.

Send/attempt operations are not replay-safe: on an ambiguous result inspect status/history/destination before trying again.

The status replay’s widgetAttempt.status is the persisted model lifecycle value (pending, captcha_solved, otp_requested, verified, failed, expired); the top-level replay outcome separately uses pending/success/failed. A completed model attempt remains verified, even when the replay outcome is success.

Own recovery guidance

CodeHint
MISSING_WIDGET_IDNo widget has this --public-key. Use the publicKey (pk_…) shown by akedly widgets create or akedly widgets get <id>, not the _id or the widgetId.
INVALID_SIGNATUREThe signature did not match. Check that --widget-secret-file holds this widget's Secret (shown once by akedly widgets create) and that --public-key belongs to the same widget.
INVALID_PUBLIC_KEYCheck --public-key against the publicKey returned by akedly widgets get <id>.

Common error guidance.