Skip to content
Akedly
Command reference

Integrations, bans and webhook verification

Akedly CLI command reference: Integrations, bans and webhook verification.

integrations list

See every integration on your account, meaning each OTP or one-way messaging integration, with its type, its recent activity and the gateway screens connected to it, before choosing one for a flow.

When to use

  • Use this to find the integration ID to send as pipelineID, or to see which integrations use a hosted gateway screen, which are headless and which are still legacy.
  • Use it to spot gateway screens that are connected to no integration, or a gateway integration that has no screen yet.

How it works

  1. Reads the session account's integrations and their active or suspended gateway screens in one unpaginated request; it changes nothing.
  2. The server decides each type at read time: an integration with a connected screen is gateway whatever version it stores, a gateway integration without one is gateway_not_connected, headless is headless and legacy or no version is legacy; utility integrations have type null.
  3. auths24h counts requests in the last 24 hours, successRate7d is the share of successful verifications in the last 7 days, and lastActivityAt is the time of the newest request in the last 7 days; all three leave out Developer mode test number traffic, and an integration with no traffic in the last 7 days shows 0, 100 and null.
  4. successRate24h is the share of successful sends in the last 24 hours, to one decimal, and null when the integration sent nothing in that time; lowSuccess24h is true when the integration sent more than the account-wide minimum (50 by default) in the last 24 hours and its successRate24h is lower than the threshold (70% by default), the same warning the dashboard Home shows. Both leave out Developer mode test number traffic, and both are null, like the other activity numbers, when the activity read fails.

Prerequisites

  • A CLI login with pipelines:read or utilities:read for this account; with only one of them, the list shows only that product's integrations.
  • widgets:read adds screens and unattachedScreens; without it both are left out.

Expected outcome

data.integrations lists each integration with its _id, name, product, type, createdAt and activity numbers; with widgets:read each one carries its screens and data.unattachedScreens lists the screens connected to no integration.

Next steps

  • Use the flow for its type: for gateway, take a connected screen's publicKey from screens, then run akedly otp gateway attempt with that publicKey and the screen Secret saved at creation; for headless, send the integration _id as pipelineID with akedly otp headless send; for legacy, send it as pipelineID with akedly otp legacy create. A gateway_not_connected integration needs a screen first (akedly integrations screens create).
  • Read one integration's full settings with akedly integrations get <id>.
  • Connect an unattached screen with akedly integrations screens update <id> --integration-id <integrationId>, or give a gateway_not_connected integration a screen with akedly integrations screens create.

Usage

sh
akedly integrations list

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations list" --output json

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: pipelines:read.

Server request: GET /integrations.

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

List your integrations: each OTP or one-way messaging integration, with its type, its requests in the last 24 hours, its 7-day success rate and its last activity. An integration _id is the integration ID that headless and legacy API calls send as pipelineID; gateway calls use a screen publicKey instead. The type is gateway (uses Akedly's hosted gateway screens, the screens from akedly integrations screens list), gateway_not_connected (a gateway integration with no screen yet), headless (formerly V1.2; you build the screens) or legacy (formerly V1, or no version; legacy is sunset on 30 December 2026). One-way messaging integrations have product utility and type null. mode is Live or Test, the integration's environment (a gateway integration needs both the Return URL and the Server URL before it can be Live). devMode.expiresAt is when developer mode ends, or null when it is off; each listed screen carries its own devMode.expiresAt. With widgets:read, each integration lists its connected gateway screens (each with its _id, widgetId and publicKey) and data.unattachedScreens lists the screens connected to no integration; inactive screens are left out. Needs pipelines:read or utilities:read, and each shows only its own product. The activity numbers are null when they could not be read; the list still loads. The list is not paginated. Read-only logins are supported.

Login 429 guidance.

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 integrations list workflow

See every integration on your account, meaning each OTP or one-way messaging integration, with its type, its recent activity and the gateway screens connected to it, before choosing one for a flow.

sh
akedly integrations list

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "message": "Integrations retrieved successfully",
  "data": {
    "integrations": [
      {
        "_id": "0123456789abcdef01234567",
        "name": "Example sign-in",
        "product": "otp",
        "type": "gateway",
        "mode": "Test",
        "createdAt": "2026-01-01T09:00:00.000Z",
        "devMode": {
          "expiresAt": null
        },
        "auths24h": 12,
        "successRate7d": 96,
        "successRate24h": 91.7,
        "lowSuccess24h": false,
        "lastActivityAt": "2026-01-08T08:30:00.000Z",
        "screens": [
          {
            "_id": "0123456789abcdef0123456a",
            "widgetId": "widget_0123456789abcdef0123456789abcdef",
            "publicKey": "pk_0123456789abcdef0123456789abcdef0123456789abcdef",
            "name": "Example sign-in screen",
            "status": "active",
            "createdAt": "2026-01-01T09:05:00.000Z"
          }
        ]
      },
      {
        "_id": "0123456789abcdef01234568",
        "name": "Example new gateway",
        "product": "otp",
        "type": "gateway_not_connected",
        "mode": "Test",
        "createdAt": "2026-01-05T09:00:00.000Z",
        "devMode": {
          "expiresAt": null
        },
        "auths24h": 0,
        "successRate7d": 100,
        "successRate24h": null,
        "lowSuccess24h": false,
        "lastActivityAt": null,
        "screens": []
      }
    ],
    "unattachedScreens": [
      {
        "_id": "0123456789abcdef0123456b",
        "name": "Example spare screen",
        "status": "active",
        "createdAt": "2026-01-04T09:00:00.000Z"
      }
    ]
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

The unattached screen can be connected to the gateway_not_connected integration with akedly integrations screens update <id> --integration-id <integrationId>.

Additional command forms

sh
akedly integrations list

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

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

type is null exactly when product is utility. A gateway integration has at least one screen; its stored API version can be legacy or gateway, because its screen traffic runs as gateway.

screens and unattachedScreens appear only when the login may read screens (widgets:read). Inactive screens and Akedly's own sandbox integrations and screens are never listed.

Integrations of a product the login cannot read are left out: pipelines:read shows OTP integrations and utilities:read shows one-way messaging integrations.

mode is Live or Test (Test when never set). devMode.expiresAt is the end of the one-hour developer mode window, or null when developer mode is off or has run out; screens carry the same field for their own developer mode.

Common error guidance.

integrations create

Create a headless or gateway integration in one command: its OTP integration and, for gateway, its first gateway screen.

When to use

  • Use headless when your own app shows the code screens and calls the API; use gateway when you want Akedly's hosted gateway screen.
  • Use it instead of running akedly integrations create and akedly integrations screens create one after the other for a new integration.

How it works

  1. Sends one request. The server creates the integration owned by your account (headless for headless, gateway for gateway) and, for gateway, a screen connected to it.
  2. Both one-time secrets go to private files when you give --secret-file and --screen-secret-file; the screen Secret is never printed.
  3. If the screen is refused after the integration was created, the integration is kept and the command reports PARTIAL_UPDATE with a recovery command.

Prerequisites

  • A Full access CLI login with pipelines:create; gateway also needs widgets:create.
  • For gateway, a new private --screen-secret-file path; both the Return URL and the Server URL before it can go live.

Expected outcome

data.integration is the new integration with its integration type, and for gateway data.screen is its connected screen; secrets are replaced by secretFile when written to files.

Next steps

  • The integration is already on and in Test; when its Return URL and Server URL are set, switch it to Live with akedly integrations update <id> --environment live --yes.
  • For headless, send codes with akedly otp headless send using the integration _id as pipelineID; for gateway, run akedly otp gateway attempt with the screen publicKey and the screen Secret file.
  • After PARTIAL_UPDATE, keep the integration, fix details.error and run details.recovery; do not repeat create.

Usage

sh
akedly integrations create

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations create" --output json

Flags

FlagTypeEnum / rangeRequiredDescription
--ksaboolean switch—noSelect the KSA deployment.
--typeenumheadless | gatewayyesCommand-specific option; see the full command details below. Manifest body field: type.
--nametext—yesCommand-specific option; see the full command details below. Manifest body field: name.
--verification-methodslist—noCommand-specific option; see the full command details below. Manifest body field: channels.
--redirect-urltext—noCommand-specific option; see the full command details below. Manifest body field: frontendCallbackURL. Tip: For a web page, use an https:// redirect URL; http:// is sent unencrypted, so keep it for a local test server. An app deep link such as yourapp://callback keeps its own scheme, which your app must handle.
--webhook-urltext—noCommand-specific option; see the full command details below. Manifest body field: backendCallbackURL. Tip: Use an https:// webhook URL; http:// is sent unencrypted, so keep it for a local test server. Test the endpoint before it receives production traffic.
--screen-nametext—noCommand-specific option; see the full command details below. Manifest body field: screen.name.
--cluster-gate-home-countrieslist—noCommand-specific option; see the full command details below. Manifest body field: homeCountries.
--secret-filetext—noWrite the secret to a new mode 0600 file and omit it from output; an existing path is refused.
--screen-secret-filetext—noCommand-specific option; see the full command details below.
--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: login. Permission: pipelines:create.

Server request: POST /integrations.

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: secret-sink. Use the supported sink; default output may contain a secret. Supported sinks: --secret-file.

Full command details

Create an integration in one step with --type headless|gateway and --name. Headless creates a headless OTP integration that your own screens call with akedly otp headless send. Gateway creates a gateway OTP integration and its first gateway screen; it needs widgets:create as well as pipelines:create. --redirect-url and --webhook-url are optional while the integration is in test, and both must be set before it can switch to live with akedly integrations update <id> --environment live. --verification-methods takes a comma list of whatsapp, telegram, sms and email, each at most once, sent in the order you type; without it the integration gets WhatsApp, SMS and email. --cluster-gate-home-countries takes the ISO codes of the countries most of your users are in, comma separated (EG,SA); they are saved as the integration's Cluster Gate home countries only where Cluster Gate takes them on this server, and otherwise left out without an error, so check data.clusterGateHomeCountries with akedly integrations get <id>; to set them later, use --cluster-gate-home-countries on akedly integrations update. --screen-name names the gateway screen and defaults to the integration name. The integration is created on (active) and in Test, so it can send test codes at once; turn it off with akedly integrations update <id> --status inactive --yes if it should not send yet. --secret-file <new path> saves the webhook signing secret like akedly integrations create; without it data.integration.webhookSigningSecret stays in the JSON output and can be revealed later with akedly integrations webhook-secret reveal. A real gateway run needs --screen-secret-file <new path>, which receives the screen's one-time screen Secret, mode 0600, never printed and never shown again; akedly otp gateway attempt reads that file. If the integration is created but its screen is refused, the command fails with PARTIAL_UPDATE: the integration is kept, details.error says why, and details.recovery creates the screen; WIDGET_PIPELINE_NOT_READY says what the integration is missing. Do not repeat create after a partial or ambiguous result; run akedly integrations list first. --dry-run shows the request and sends nothing.

Login 429 guidance.

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 gateway integration workflow

Create a gateway integration with its first gateway screen and save both one-time secrets to private files.

sh
akedly integrations create --type gateway --name 'Example sign-in' --redirect-url https://example.invalid/done --webhook-url https://example.invalid/webhook --verification-methods whatsapp,sms --secret-file ./private/webhook-secret.txt --screen-secret-file ./private/widget-secret.txt

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "message": "Integration created successfully",
  "data": {
    "integration": {
      "_id": "0123456789abcdef01234567",
      "name": "Example sign-in",
      "type": "gateway",
      "active": false,
      "securityConfig": {
        "apiVersion": "v2"
      },
      "secretFile": "./private/webhook-secret.txt"
    },
    "screen": {
      "_id": "0123456789abcdef0123456a",
      "name": "Example sign-in",
      "widgetId": "widget_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "publicKey": "pk_synthetic",
      "pipelineId": "0123456789abcdef01234567",
      "secretFile": "./private/widget-secret.txt"
    }
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Secret output sinks: ./private/webhook-secret.txt and ./private/widget-secret.txt. Use new private paths when running the command; the synthetic example is documentation only.

The integration starts on (active) and in Test.

Synthetic headless integration workflow

Create a headless integration for your own code screens and save its webhook signing secret.

sh
akedly integrations create --type headless --name 'Example checkout' --secret-file ./private/webhook-secret.txt

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "message": "Integration created successfully",
  "data": {
    "integration": {
      "_id": "0123456789abcdef01234567",
      "name": "Example checkout",
      "type": "headless",
      "active": false,
      "securityConfig": {
        "apiVersion": "v1.2"
      },
      "secretFile": "./private/webhook-secret.txt"
    }
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Secret output sink: ./private/webhook-secret.txt. Use a new private path when running the command; the synthetic example is documentation only.

Additional command forms

sh
akedly integrations create --type headless --name Example --verification-methods whatsapp,sms
sh
akedly integrations create --type gateway --name Example --redirect-url <url> --webhook-url <url> --secret-file <new path> --screen-secret-file <new path>

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

data.integration is the created integration as akedly integrations create returns it, with type replaced by the integration type (headless, gateway or gateway_not_connected), not the Live or Test environment.

The server reports a refused screen as data.screenError on a 201 response; the CLI turns it into PARTIAL_UPDATE, so successful CLI output never carries screenError.

Secret bytes go only to the requested files; without --secret-file, data.integration.webhookSigningSecret stays in the JSON output.

Common error guidance.

integrations upgrade

Move a headless integration onto Akedly's hosted gateway screen without rebuilding its settings, keeping the old integration working until the app switches over.

When to use

  • Use when a person wants a headless integration to use the hosted gateway (hosted screens, stronger bot and agent detection) and agrees that their app will switch to new keys.

How it works

  1. Sends one request. The server creates a new gateway integration, copies the settings that mean the same on a gateway, links the two both ways and creates one new gateway screen with standard gateway limits.
  2. The old integration is left on and unchanged apart from the link, and gateway screens already connected to it stay with it, so live traffic keeps working until the app uses the new integration's screen publicKey.
  3. Both one-time secrets go to private files when you give --secret-file and --screen-secret-file; the screen Secret is never printed.

Prerequisites

  • A Full access CLI login with pipelines:create and widgets:create, plus whatsapp:update when the old integration uses a custom OTP message template.
  • A headless integration on this account that has not been upgraded yet and does not send SMS through a provider added only to it, and a new private --screen-secret-file path.

Expected outcome

data.integration is the new gateway integration, data.upgradedFrom names the old one, and data.screen is its new gateway screen; secrets are replaced by secretFile when written to files.

Next steps

  • Switch your app to the new integration: run akedly otp gateway attempt with the screen publicKey and the screen Secret file, point webhook verification at the new signing secret, and set the screen's rate limits with akedly integrations screens update <id> --rate-limits-file <file> --yes if the standard gateway limits do not fit.
  • When nothing uses the old keys any more, run akedly integrations delete <old id> --yes; an upgraded integration is hidden, not erased, so its history stays.

Usage

sh
akedly integrations upgrade <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations upgrade" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Use the _id of a headless integration from akedly integrations list.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--secret-filetext—Write the secret to a new mode 0600 file and omit it from output; an existing path is refused.
--screen-secret-filetext—Command-specific option; see the full command details below.
--dry-runboolean switch—Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--yesboolean switch—Confirm this action where consent is required.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: pipelines:create.

Server request: POST /integrations/:id/upgrade.

Shared server-guard guidance.

Consent

--yes. --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: secret-sink. Use the supported sink; default output may contain a secret. Supported sinks: --secret-file.

Full command details

Upgrade a headless integration (formerly V1.2) to Akedly's hosted gateway. Akedly creates a new gateway integration with new keys: a new integration ID and a new webhook signing secret. It copies onto the new integration the settings that work the same on a gateway: verification methods and their order, smart routing, channel choice, destination countries, zero-verify bans, passkeys, the own SMS provider setting, billing mode, home countries, the Return URL and Server URL, OTP language, a custom OTP message template and webhook events (each event as the old integration resolves it, so an event that was off stays off). Its integration rate limits and circuit breaker are copied too, but hosted gateway requests are limited by the gateway screen: the new screen starts with standard gateway limits, not the old integration's, so set them with akedly integrations screens update <id> --rate-limits-file <file> --yes. The upgrade creates one new gateway screen; its one-time screen Secret goes to --screen-secret-file <new path>, mode 0600, never printed. Gateway screens already connected to the old integration stay with it: they keep working with the old keys and stop when the old integration is cleaned up. The new integration is on, and Live only when the old one is Live and has both the Return URL and the Server URL; otherwise it is in Test. The old integration is not deleted: it keeps working with its old keys, and its history stays under it. akedly integrations get shows the link both ways in data.upgrade. When your app uses the new keys, clean up the old integration with akedly integrations delete <old id> --yes, which hides it and keeps its history. Because the keys change, the command always needs --yes. Only headless integrations can be upgraded (HTTP 400 INTEGRATION_NOT_UPGRADABLE), and only once (HTTP 409 INTEGRATION_ALREADY_UPGRADED, whose details.data.integrationId names the new one). An integration that sends SMS through its own provider added only to it is refused with HTTP 409 INTEGRATION_HAS_OWN_SMS_PROVIDER before anything is created. Needs pipelines:create and widgets:create, plus whatsapp:update when the old integration uses a custom OTP message template (otherwise HTTP 403 and nothing is created). --secret-file <new path> saves the new webhook signing secret like akedly integrations create; without it data.integration.webhookSigningSecret stays in the JSON output. If the new integration is created but its screen is refused, the command fails with PARTIAL_UPDATE: details.error says why and details.recovery creates the screen; do not repeat the upgrade. --dry-run shows the request and sends nothing.

Login 429 guidance.

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 upgrade of a headless integration

Move a headless integration onto Akedly's hosted gateway screen.

sh
akedly integrations upgrade 0123456789abcdef01234567 --secret-file ./private/new-webhook-secret.txt --screen-secret-file ./private/screen-secret.txt --yes

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "message": "Integration upgraded successfully",
  "data": {
    "integration": {
      "_id": "0123456789abcdef01234568",
      "name": "Example checkout",
      "type": "gateway",
      "active": true,
      "securityConfig": {
        "apiVersion": "v2"
      },
      "upgrade": {
        "from": "0123456789abcdef01234567",
        "at": "2026-01-08T09:00:00.000Z"
      },
      "secretFile": "./private/new-webhook-secret.txt"
    },
    "upgradedFrom": {
      "_id": "0123456789abcdef01234567",
      "name": "Example checkout"
    },
    "screen": {
      "_id": "0123456789abcdef0123456a",
      "name": "Example checkout",
      "widgetId": "widget_0123456789abcdef0123456789abcdef",
      "publicKey": "pk_0123456789abcdef0123456789abcdef0123456789abcdef",
      "pipelineId": "0123456789abcdef01234568",
      "secretFile": "./private/screen-secret.txt"
    }
  }
}

Both secrets were written to the private files named on the command line and are not printed.

The old integration keeps working until it is cleaned up with akedly integrations delete <old id> --yes.

Additional command forms

sh
akedly integrations upgrade <id> --secret-file <new path> --screen-secret-file <new path> --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

Response examples are synthetic. API may include additional response fields where the schema allows them.

data.integration.type is the integration type (gateway once a screen is connected), not the Live or Test environment.

The server reports a refused screen as data.screenError on a 201 response; the CLI turns it into PARTIAL_UPDATE, so successful CLI output never carries screenError.

Own recovery guidance

CodeHint
INTEGRATION_ALREADY_UPGRADEDThis integration was already upgraded; details.data.integrationId or akedly integrations get <id> (data.upgrade.to) names the new one. Use that integration; do not upgrade again.
INTEGRATION_NOT_UPGRADABLEOnly headless integrations (formerly V1.2) can be upgraded. Check the type with akedly integrations list; a legacy integration needs a new integration instead (akedly integrations create --type gateway).
INTEGRATION_HAS_OWN_SMS_PROVIDERNothing was created. This integration sends SMS through its own provider, added only to it, which an upgrade can't carry over yet. In the dashboard, remove that provider under Providers on this integration on the Channels tab (SMS then goes through your other providers or Akedly), run the upgrade again, then add the provider to the new integration with Add from your providers and send a test.

Common error guidance.

integrations get

Inspect one integration’s current API version, Return URL and Server URL, verification methods, billing and security settings before changing or integrating it.

When to use

  • Use before updating settings or diagnosing an integration-specific rejection.

How it works

  1. Reads the integration by its Mongo ID and returns the server resource.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

The current integration resource.

Next steps

  • Use the current settings as the basis for an update; the CLI reads revisions automatically when settings require conflict protection.

Usage

sh
akedly integrations get <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations get" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Required positional argument.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: pipelines:read.

Server request: GET /pipelines/id/:id.

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

Read an integration, including its Return URL (frontendCallbackURL) and Server URL (backendCallbackURL). data.lastSuccessAt is the time of its newest successful verification (test traffic left out), or null; data.hasSucceededEver is true once it has had one. data.upgrade links an upgraded integration both ways: from (the headless integration it was upgraded from) or to (the gateway integration it was upgraded to), each with _id, name and hidden, plus at; it is null when the integration was never upgraded.

Login 429 guidance.

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 integrations get workflow

Inspect one integration’s current API version, Return URL and Server URL, verification methods, billing and security settings before changing or integrating it.

sh
akedly integrations get 0123456789abcdef01234567

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "0123456789abcdef01234567",
    "name": "Example OTP",
    "active": false,
    "type": "Test",
    "securityConfig": {
      "apiVersion": "v1.2"
    },
    "hasAttachedWidget": false,
    "clusterGateHomeCountries": [],
    "channelChoice": {
      "enabled": false
    },
    "updatedAt": "2030-03-12T09:00:00.000Z"
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Additional command forms

sh
akedly integrations get <id>
sh
akedly integrations get <id> --fields data.frontendCallbackURL,data.backendCallbackURL

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

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Common error guidance.

integrations update

Change an integration’s customer-facing verification, routing, country, branding, or security behavior while preserving concurrent edits.

When to use

  • Use to adjust an existing integration after checking its API version and attached screens.

How it works

  1. For revision-protected settings, reads the current integration revision and includes it in the write to reject stale edits. On legacy and gateway, screen-only controls fan out to every active and inactive attached screen after a paginated attachment read; on headless they are refused. Dry-run performs planning reads and returns either a raw single-request preview or an ordered multi-resource steps plan.
  2. --webhook-channels-resolved on|off selects otp.channels.resolved, --webhook-channels-updated on|off selects otp.channels.updated, and --webhook-delivery-receipts on|off selects otp.message.status. These optional webhook choices are OTP-only and stay on the integration; verification results are always sent. Turning a choice off prevents new events; already queued retries can still arrive.
  3. Only supplied webhook choices are patched, including off:false; omitted choices keep their saved or unset state. An unset legacy choice uses server version defaults (legacy/headless channel events on and delivery receipts off; gateway all three off). Receipt-only changes need no planning read. Utility updates rely on server rejection.
  4. A configured --webhook-url is required. Eligible live headless and gateway requests qualify; legacy also requires waitForChannels:true. Delivery receipts currently cover WhatsApp and Akedly-routed Egyptian SMS, not international or BYO-SMS routes, Telegram or email. Test transactions produce no optional OTP events.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

Updated integration resource, or a dry-run plan; an ordered fan-out can fail with PARTIAL_UPDATE after some resources were saved.

Next steps

  • Inspect every resource named by PARTIAL_UPDATE before retrying; use integrations get and integrations screens list-filtered including inactive screens.

Usage

sh
akedly integrations update <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations update" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Required positional argument.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--nametext—Command-specific option; see the full command details below. Manifest body field: name.
--descriptiontext—Command-specific option; see the full command details below. Manifest body field: description.
--statusenumactive | inactiveCommand-specific option; see the full command details below. Manifest body field: active.
--environmentenumlive | testCommand-specific option; see the full command details below. Manifest body field: type.
--otp-languageenumen | arCommand-specific option; see the full command details below. Manifest body field: locale.
--redirect-urltext—Command-specific option; see the full command details below. Manifest body field: frontendCallbackURL. Tip: For a web page, use an https:// redirect URL; http:// is sent unencrypted, so keep it for a local test server. An app deep link such as yourapp://callback keeps its own scheme, which your app must handle.
--webhook-urltext—Command-specific option; see the full command details below. Manifest body field: backendCallbackURL. Tip: Use an https:// webhook URL; http:// is sent unencrypted, so keep it for a local test server. Test the endpoint before it receives production traffic.
--smart-routingenumon | offCommand-specific option; see the full command details below. Manifest body field: smartRouting.
--passkeysenumon | offCommand-specific option; see the full command details below. Manifest body field: passkeyEnabled. Tip: Passkeys let returning users verify with Face ID or a fingerprint, and a passkey sign-in can cost up to 40% less than an OTP at the default passkey rate; your account's rate may differ.
--zero-verify-bansenumon | offCommand-specific option; see the full command details below. Manifest body field: zeroVerifyBansEnabled. Tip: Keep zero-verify bans on, as they are by default; when they are off, account-level zero-verify bans no longer stop requests to this integration.
--dry-runboolean switch—Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--byo-smsenuminherit | on | offCommand-specific option; see the full command details below. Manifest body field: byoSms.
--yesboolean switch—Confirm this action where consent is required.
--cluster-gateenumon | offCommand-specific option; see the full command details below. Manifest body field: securityConfig.clusterGate.enabled, clusterGateIntent.
--cluster-gate-positionenumcautious | balanced | assertiveCommand-specific option; see the full command details below. Manifest body field: securityConfig.clusterGate.position, clusterGateIntent. Tip: Balanced is the default position. Estimated during an attack, Cautious blocks about 65% of spam and refuses no real users, Balanced about 90% of spam and about 1% of real users, and Assertive 95% or more of spam and about 3% of real users. Assertive is outside Akedly's recommended limits: it does not check whether a request is a real user caught in the same flood. Refusals are rare outside an attack.
--cluster-gate-escalationenumon | offCommand-specific option; see the full command details below. Manifest body field: securityConfig.clusterGate.escalation, clusterGateIntent.
--cluster-gate-home-countrieslist—Command-specific option; see the full command details below. Manifest body field: securityConfig.clusterGate.homeCountries, clusterGateIntent. The literal none clears this value. Tip: Declare the countries where you expect phone destinations and end-user IPs to help Cluster Gate understand your traffic. Home countries do not restrict sending or allow or block IP addresses, and other protections still apply. Learned countries stay included automatically; clearing declarations does not clear the learned set.
--verification-methodslist—Command-specific option; see the full command details below. Manifest body field: verificationMethods. Tip: Akedly recommends WhatsApp first, for the most reliable delivery and a lower price than SMS. With automatic order, WhatsApp is already the default first channel, even when your list leaves it out, and your list decides the fallbacks; to keep WhatsApp out or to send in your own order, pass --method-order custom and list the methods in that order, because a list alone keeps the integration's current order setting.
--method-orderenumcustom | automaticCommand-specific option; see the full command details below. Manifest body field: useMethodOrder. Tip: Akedly recommends WhatsApp first, for the most reliable delivery and a lower price than SMS. With automatic order, WhatsApp is already the default first channel, even when your list leaves it out, and your list decides the fallbacks; to keep WhatsApp out or to send in your own order, pass --method-order custom and list the methods in that order, because a list alone keeps the integration's current order setting.
--channel-choiceenumon | offCommand-specific option; see the full command details below. Manifest body field: channelChoiceEnabled.
--channel-choice-modeenumask-first | send-firstCommand-specific option; see the full command details below. Manifest body field: channelChoiceMode.
--channel-choice-enforcementenumfallback | hard-pinCommand-specific option; see the full command details below. Manifest body field: channelChoiceEnforcement.
--rate-limits-filetext—Command-specific option; see the full command details below. Manifest body field: rateLimiting.perEndUserIP.perDay, rateLimiting.perEndUserIP.perHour, rateLimiting.perEndUserIP.perMinute, rateLimiting.perPhoneNumber.perDay, rateLimiting.perPhoneNumber.perHour, rateLimiting.perPhoneNumber.perMinute, rateLimiting.perPipeline.perDay, rateLimiting.perPipeline.perHour, rateLimiting.perPipeline.perMinute, expectedUpdatedAt. Tip: Start with the default limits unless your traffic needs different ones. Use traffic recommendations when enough history is available; their calculations include a 10% growth buffer. Final screen recommendations also apply per-phone and per-device caps and may raise per-screen hour and day limits to meet the required ratios, so applied values can differ from the buffered calculation. Review the result against expected peaks before changing live limits.
--circuit-breakerenumon | offCommand-specific option; see the full command details below. Manifest body field: circuitBreaker.enabled. Tip: Keep the circuit breaker on; Akedly recommends it to protect verification from flood attacks and traffic spikes.
--circuit-breaker-sensitivityenumstrict | balanced | lenientCommand-specific option; see the full command details below. Manifest body field: circuitBreakerMultiplier.
--destination-countries-modeenumall | only-selected | all-except-selectedCommand-specific option; see the full command details below. Manifest body field: countryPolicy.mode, expectedUpdatedAt.
--destination-countrieslist—Command-specific option; see the full command details below. Manifest body field: countryPolicy.countries, expectedUpdatedAt.
--recommended-limitsboolean switch—Command-specific option; see the full command details below. Manifest body field: rateLimiting.perPipeline.perMinute, rateLimiting.perPipeline.perHour, rateLimiting.perPipeline.perDay, expectedUpdatedAt. Tip: Start with the default limits unless your traffic needs different ones. Use traffic recommendations when enough history is available; their calculations include a 10% growth buffer. Final screen recommendations also apply per-phone and per-device caps and may raise per-screen hour and day limits to meet the required ratios, so applied values can differ from the buffered calculation. Review the result against expected peaks before changing live limits.
--periodenumlast-month | last-quarter | last-6-monthsCommand-specific option; see the full command details below.
--otp-templatetext—Command-specific option; see the full command details below. Manifest body field: defaultOtpTemplateId.
--api-versionenumv1 | v1.2 | v2Command-specific option; see the full command details below. Manifest body field: securityConfig.apiVersion, expectedUpdatedAt. Tip: Use v2 (gateway) if you will embed Akedly's hosted screen, and v1.2 (headless) if you will build the verification screens yourself or cannot embed an iframe or open a system browser. v1 (legacy) sunsets on December 30, 2026.
--pow-starting-difficultytext—Command-specific option; see the full command details below. Manifest body field: securityConfig.pow.difficulty, expectedUpdatedAt.
--pow-auto-scalingenumon | offCommand-specific option; see the full command details below. Manifest body field: securityConfig.pow.autoScaling, expectedUpdatedAt.
--passkey-company-nametext—Command-specific option; see the full command details below. Manifest body field: passkeyBranding.customCompanyName, expectedUpdatedAt.
--passkey-logo-urltext—Command-specific option; see the full command details below. Manifest body field: passkeyBranding.customLogo, expectedUpdatedAt.
--passkey-primary-colortext—Command-specific option; see the full command details below. Manifest body field: passkeyBranding.customPrimaryColor, expectedUpdatedAt.
--passkey-secondary-colortext—Command-specific option; see the full command details below. Manifest body field: passkeyBranding.customSecondaryColor, expectedUpdatedAt.
--passkey-themeenumlight | dark | systemCommand-specific option; see the full command details below. Manifest body field: passkeyBranding.theme, expectedUpdatedAt.
--turnstileenumon | offCommand-specific option; see the full command details below. Manifest body field: securityConfig.turnstile.enabled, expectedUpdatedAt.
--turnstile-allowed-domainslist—Command-specific option; see the full command details below. Manifest body field: securityConfig.turnstile.domains, expectedUpdatedAt.
--turnstile-platformenumweb | mobileCommand-specific option; see the full command details below. Manifest body field: securityConfig.turnstile.platform, expectedUpdatedAt.
--turnstile-site-keytext—Command-specific option; see the full command details below. Manifest body field: securityConfig.turnstile.siteKey, expectedUpdatedAt.
--turnstile-test-tokentext—Command-specific option; see the full command details below. Manifest body field: securityConfig.turnstile.testToken, expectedUpdatedAt.
--turnstile-secret-key-filetext—Command-specific option; see the full command details below. Manifest body field: securityConfig.turnstile.secretKey, expectedUpdatedAt.
--circuit-breaker-filetext—Command-specific option; see the full command details below. Manifest body field: circuitBreaker.floodThresholds.per15Minutes, circuitBreaker.floodThresholds.per5Minutes, circuitBreaker.floodThresholds.perMinute, circuitBreaker.suspensionDurations.firstViolation, circuitBreaker.suspensionDurations.maxViolation, circuitBreaker.suspensionDurations.secondViolation, expectedUpdatedAt. Tip: Keep the circuit breaker on; Akedly recommends it to protect verification from flood attacks and traffic spikes.
--powenumon | offCommand-specific option; see the full command details below. Manifest body field: security.pow.allowed, expectedUpdatedAt. Tip: Keep the default proof-of-work settings unless you face sustained heavy abuse. For an expected launch or campaign surge, raise the rate limits and circuit breaker flood thresholds first instead of lowering the proof-of-work trigger, so legitimate traffic is not challenged too early.
--pow-trigger-percentinteger25 to 95Command-specific option; see the full command details below. Manifest body field: security.pow.triggerPercent, expectedUpdatedAt. Tip: Keep the default proof-of-work settings unless you face sustained heavy abuse. For an expected launch or campaign surge, raise the rate limits and circuit breaker flood thresholds first instead of lowering the proof-of-work trigger, so legitimate traffic is not challenged too early.
--pow-maximum-difficultyinteger3 to 6Command-specific option; see the full command details below. Manifest body field: security.pow.maxDifficulty, expectedUpdatedAt. Tip: Keep the default proof-of-work settings unless you face sustained heavy abuse. For an expected launch or campaign surge, raise the rate limits and circuit breaker flood thresholds first instead of lowering the proof-of-work trigger, so legitimate traffic is not challenged too early.
--webhook-channels-resolvedenumon | offCommand-specific option; see the full command details below. Manifest body field: webhookEvents.channelsResolved.
--webhook-channels-updatedenumon | offCommand-specific option; see the full command details below. Manifest body field: webhookEvents.channelsUpdated.
--webhook-delivery-receiptsenumon | offCommand-specific option; see the full command details below. Manifest body field: webhookEvents.messageStatus.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: pipelines:update.

Server request: PUT /pipelines/id/:id.

Shared server-guard guidance.

Consent

--yes when --status or --environment or --otp-language or --smart-routing or --passkeys or --zero-verify-bans or --byo-sms or --cluster-gate or --cluster-gate-position or --cluster-gate-escalation or --cluster-gate-home-countries or --verification-methods or --method-order or --channel-choice or --channel-choice-mode or --channel-choice-enforcement or --rate-limits-file or --circuit-breaker or --circuit-breaker-sensitivity or --destination-countries-mode or --destination-countries or --recommended-limits or --otp-template or --api-version or --pow-starting-difficulty or --pow-auto-scaling or --passkey-company-name or --passkey-logo-url or --passkey-primary-color or --passkey-secondary-color or --passkey-theme or --turnstile or --turnstile-allowed-domains or --turnstile-platform or --turnstile-site-key or --turnstile-test-token or --turnstile-secret-key-file or --circuit-breaker-file or --pow or --pow-trigger-percent or --pow-maximum-difficulty or --redirect-url or --webhook-url or --webhook-channels-resolved or --webhook-channels-updated or --webhook-delivery-receipts is given. --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

Retry exception: an integrations update that changes rate limits or destination countries is not retried automatically after a timeout or server error, because it may already be saved; check with akedly integrations get <id>, and running the same command again is safe. Update only the flags you supply: --name, --description, --status active|inactive, --environment live|test, --otp-language en|ar, --redirect-url, --webhook-url, --smart-routing on|off, --passkeys on|off, --zero-verify-bans on|off, --byo-sms inherit|on|off, --cluster-gate on|off, --cluster-gate-position cautious|balanced|assertive, --cluster-gate-escalation on|off, --cluster-gate-home-countries EG,SA (or none), --verification-methods, --method-order custom|automatic, --channel-choice on|off, --channel-choice-enforcement fallback|hard-pin and --channel-choice-mode ask-first|send-first. Results show status as the active field (true or false) and environment as the type field (Live or Test). Use none to clear the Return URL or the Server URL. Cluster Gate is Akedly's AI protection that refuses code requests that look like part of an attack: --cluster-gate turns it on or off for this integration, --cluster-gate-position chooses how much it refuses during an attack, and --cluster-gate-escalation on|off controls a stricter window that lasts 15 minutes after Cluster Gate last detects an attack; while that window is open, Cluster Gate can refuse every request to this integration, or only requests to unusual destinations when the attack targets numbers outside your usual countries. --cluster-gate-home-countries EG,SA replaces the complete declared home-country list for this integration, so include every country you want to keep. Omit the flag to preserve the saved declarations. Use the exact lowercase value none on its own to clear them; do not combine none with country codes. Use comma-separated two-letter country codes. Codes are normalized to uppercase, duplicates are removed, and the server saves a sorted list; an unknown code is refused rather than dropped. These declarations guide Cluster Gate for expected phone destinations and end-user IP countries. They do not restrict sending or allow or block IP addresses; destination-country restrictions and other protections still apply. Learned countries are managed separately by the engine; replacing or clearing declarations does not edit or erase learned countries or their history. This flag needs --yes whenever supplied, including none or the current list. A home-country-only --dry-run previews the declaration without --yes or requests; the server checks country membership and Cluster Gate availability on the real update. Read saved declarations with akedly integrations get <id> in data.securityConfig.clusterGate.homeCountries; data.clusterGateHomeCountries contains separate learned-country metadata. This flag also works on integrations screens create and update, changing the linked integration. The CLI sends only the Cluster Gate settings you supply, plus the intent marker the server requires, so the others keep their values. If Cluster Gate cannot be changed on this integration, the command fails with CLUSTER_GATE_NOT_AVAILABLE, details.reason says why, and nothing in that request is saved; --dry-run cannot check this. --verification-methods takes a comma list of whatsapp, telegram, sms and email, each at most once; it replaces the whole list, so include every method you want to keep, it cannot be empty, and email always goes last. The order you type is used whenever the integration uses custom order, because you pass --method-order custom or the integration already has it. The CLI reads Akedly's public list of verification methods, which needs no login, to find each one; even a dry run makes this one read, though it changes nothing. A word with no available method is refused as VERIFICATION_METHOD_UNAVAILABLE before anything is saved. On legacy pricing, SMS cannot be the only phone method; add whatsapp or telegram. --method-order custom sends through your methods in the listed order. With automatic order, WhatsApp is the default first channel even when your list leaves it out, sent from Akedly's shared number unless you connected your own; two things can start a send elsewhere: a channel the user picked through Channel Choice, and Smart Routing, which sends someone's next code on the next channel when an earlier WhatsApp code to that number has not been confirmed as delivered. Your list then decides the fallbacks, Telegram and then SMS, only those you listed, whatever order you typed them in. To keep WhatsApp out or to send in the order you typed, use --method-order custom; email is unaffected. --method-order is sent only when you pass it, so a list alone does not change the order setting and the integration keeps the one it has, except that a list with exactly one phone method (email not counted) is always saved with custom order, even with --method-order automatic; pass --method-order whenever the order matters. akedly integrations get <id> shows the current methods as ids in data.verificationMethods, the order setting in data.useMethodOrder (true means custom), data.hasAttachedWidget and the Channel Choice summary in data.channelChoice, including blockers, eligibleChannels and fallbackOrder. --channel-choice on|off lets users choose where to get their code. If their channel fails later, --channel-choice-enforcement fallback tries another channel and hard-pin uses only their choice; with custom order, fallback tries the next listed channel, and with automatic order it follows WhatsApp, then Telegram, then SMS among the methods in your list, so an unlisted WhatsApp is never a Channel Choice fallback. --channel-choice-mode sets the screen experience: ask-first lets users choose before a code is sent, and send-first sends a code, then offers a choice on resend; it applies only to gateway integrations with a screen attached, so changing it on any other integration fails with SETTING_NOT_FOR_THIS_PIPELINE, while setting the mode the integration already has (ask-first when none is stored) skips that check, though another Channel Choice flag that changes in the same command can still be refused. Channel Choice needs it enabled on your account, granular pricing and pay-per-message billing, and it is also blocked on a one-way messaging integration, for an excluded account or while Akedly has it switched off for everyone. A command that changes a Channel Choice value is then refused with CHANNEL_CHOICE_NOT_AVAILABLE and details.blockers names the reason, while a value the integration already has, such as off when it is already off or was never set, is accepted. --rate-limits-file <file> reads a JSON object of the limits to change, for example {"perPipeline":{"perMinute":30}}: perPhoneNumber, perIpAddress and perPipeline each take perMinute, perHour and perDay as whole numbers above zero, only the limits you name change, and every other limit is kept. --circuit-breaker on|off turns the circuit breaker on or off, and --circuit-breaker-sensitivity strict|balanced|lenient sets how much traffic above your rate limits it tolerates before it suspends the integration; strict tolerates the least. On headless these change the integration. On legacy or gateway the CLI applies rate limits, the circuit breaker and recommended limits to every attached screen, including inactive screens; use the screen rate-limit file shape, with widgetAttempts and otpRequests containing perPhoneNumber, perDevice and perWidget. --circuit-breaker-file, --pow, --pow-trigger-percent and --pow-maximum-difficulty are screen settings and are refused on headless. --pow-starting-difficulty accepts adaptive or 2..7 on headless, and 3..6 on legacy/gateway screens. Sensitivity, Turnstile and integration passkey branding stay headless-only. If a legacy/gateway integration has no screens the command refuses with SETTING_NOT_FOR_THIS_PIPELINE and reason no-widget. The CLI checks the resulting API version when --api-version is supplied, reads both active and inactive listings through every page, checks permissions and reads every resource revision before writing. The integration saves first, then screens in creation-time/id order. If a later write fails, PARTIAL_UPDATE lists confirmed resources and unconfirmed destinations; inspect them and run the same update again. --dry-run shows every planned guarded write without saving. --recommended-limits applies Akedly's recommended integration-wide limits from your real traffic over --period last-month|last-quarter|last-6-months (default last-month), with a 10% buffer for growth; it never changes the per-phone-number or per-IP-address limits or the circuit breaker sensitivity, cannot be combined with --rate-limits-file, and is refused with NOT_ENOUGH_TRAFFIC when the analysis has low confidence or fewer than 100 requests, so a quiet integration keeps its limits. --destination-countries-mode all|only-selected|all-except-selected with --destination-countries EG,SA chooses which countries can receive codes, on every integration version. --destination-countries replaces the saved list, so include every country you want to keep; --destination-countries-mode only-selected or all-except-selected on its own keeps the saved list, so switching between them inverts it; after the list was cleared with mode all it is empty, so switching to only-selected also needs --destination-countries. To clear the list, pass --destination-countries-mode all on its own; a list sent with mode all that matches the saved list is simply cleared, and a changed list with mode all is refused with DESTINATION_COUNTRIES_MODE_REQUIRED instead of being dropped. For rate-limit and destination-country changes the CLI first reads the integration and sends the revision it read, so if someone changes the integration in between, the command fails with PIPELINE_CHANGED instead of undoing their change; run it again to read the integration again. --dry-run makes the same reads and sends no change; the integration read needs permission to read integrations, and the recommendation read for --recommended-limits needs permission to update them. Cooldowns cannot be set because they have no effect. For headless integrations, --pow-starting-difficulty adaptive|2..7 chooses the starting difficulty; Akedly can clamp it to the current policy ceiling. It does not change whether PoW is enabled. --pow-auto-scaling on|off (headless only) chooses whether Akedly raises that difficulty automatically when traffic nears the integration's rate limits; on is the default. With off, every challenge uses the starting difficulty (or the default when it is adaptive), even under attack, so bots solve challenges as fast as real users; rate limits and the circuit breaker still apply. Changing it on a legacy or gateway integration fails with SETTING_NOT_FOR_THIS_PIPELINE. --passkey-company-name, --passkey-logo-url (HTTPS), --passkey-primary-color and --passkey-secondary-color (#RRGGBB), and --passkey-theme light|dark|system override the passkey look; none clears a name, logo or colour override. --api-version changes a headless integration to gateway only; a Test integration can upgrade without a Return URL or Server URL, but a Live one needs both (--redirect-url and --webhook-url, before or in the same command). --turnstile on|off and --turnstile-platform web|mobile manage protection. A new Web integration needs --turnstile-site-key, --turnstile-secret-key-file <path|-> and --turnstile-test-token; - reads a piped secret from stdin, never pass the secret as an argument. Obtain a fresh setup token on the docs Turnstile token page; it is single-use, so obtain another after a refused or uncertain save. Mobile uses the managed shared integration. --turnstile-allowed-domains edits an enabled existing legacy Web integration only. Security, version and branding flags require --yes, read the current revision first, never repeat an uncertain write automatically, and mask credentials in --dry-run. Changing --otp-language provisions the matching WhatsApp template on your connected WABA. --byo-sms inherit|on|off uses the account setting, enables BYO-SMS or disables it for this integration; enabling it does not prove routing eligibility. Product is chosen at creation and cannot be changed here. Changing status, environment, OTP language, smart routing, passkeys, zero-verify bans, BYO-SMS, any Cluster Gate setting, the verification methods, the method order, any Channel Choice setting, the rate limits, the circuit breaker, the destination countries, the recommended limits or the Return URL or Server URL (--redirect-url or --webhook-url, including none) can stop, reroute or loosen live verification, so it needs --yes, also when it turns a protection off or loosens a limit; names, descriptions and --period do not, and --dry-run previews any change without --yes. Use --otp-template <id> to attach an OTP template approved for the integration language, or --otp-template default to restore the built-in template. A custom template needs an active WhatsApp method and your own connected WhatsApp Business Account. Both attachment and restoring the default require --yes. Find template ids and per-language approval status with akedly whatsapp otp-templates list. --webhook-channels-resolved on|off selects otp.channels.resolved, --webhook-channels-updated on|off selects otp.channels.updated, and --webhook-delivery-receipts on|off selects otp.message.status. These optional webhook choices are OTP-only and stay on the integration; verification results are always sent. Turning a choice off prevents new events; already queued retries can still arrive. A configured --webhook-url is required. Eligible live headless and gateway requests qualify; legacy also requires waitForChannels:true. Delivery receipts currently cover WhatsApp and Akedly-routed Egyptian SMS, not international or BYO-SMS routes, Telegram or email. Test transactions produce no optional OTP events. Only supplied webhook choices are patched, including off:false; omitted choices keep their saved or unset state. An unset legacy choice uses server version defaults (legacy/headless channel events on and delivery receipts off; gateway all three off). Receipt-only changes need no planning read. Utility updates rely on server rejection.

Login 429 guidance.

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 integrations update workflow

Change an integration’s customer-facing verification, routing, country, branding, or security behavior while preserving concurrent edits.

sh
akedly integrations update 0123456789abcdef01234567 --name 'Example OTP' --yes --webhook-channels-resolved off --webhook-channels-updated on --webhook-delivery-receipts off

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "0123456789abcdef01234567",
    "name": "Example OTP",
    "active": false,
    "type": "Test",
    "updatedAt": "2030-03-12T09:00:00.000Z",
    "webhookEvents": {
      "channelsResolved": false,
      "channelsUpdated": true,
      "messageStatus": false
    }
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

This example turns channel resolution off, channel updates on, and delivery receipts off; verification results remain enabled. Omitted choices follow the documented create or sparse-update semantics.

Synthetic headless integration limits and Turnstile setup

Set a per-integration request ceiling and enable the Turnstile web check for a headless integration during initial protection setup.

sh
akedly integrations update 0123456789abcdef01234567 --rate-limits-file ./fixtures/pipeline-limits.json --turnstile on --turnstile-platform web --turnstile-site-key 0x4AAAAAAAsyntheticSiteKey --turnstile-secret-key-file ./fixtures/turnstile-secret.txt --turnstile-test-token synthetic-test-token --yes

Input file: ./fixtures/pipeline-limits.json (json).

json
{
  "perPipeline": {
    "perMinute": 30
  }
}

Input file: ./fixtures/turnstile-secret.txt (text).

text
[REDACTED — use your privately saved secret file]

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "0123456789abcdef01234567",
    "name": "Example OTP",
    "active": false,
    "type": "Test",
    "updatedAt": "2030-03-12T09:00:00.000Z"
  }
}

Prerequisites: an authorized CLI login and an existing headless integration; confirm its API version and current behavior with integrations get before applying settings. The test token and all values are synthetic documentation values and are not usable credentials.

This is a confirmed write. The CLI reads the integration settings and revision before saving; dry-run still performs planning reads and previews the request. Turnstile setup-token validation can refuse the write, so use a fresh valid setup token when running for real.

The perPipeline limit controls requests across this integration. After success, inspect integrations get for saved limits and Turnstile state, then finish the provider-side hostname setup if needed.

Synthetic gateway attached-widget rate and circuit-breaker limits

Adjust request ceilings and flood protection on every screen attached to an existing gateway integration.

sh
akedly integrations update 89abcdef0123456789abcdef --rate-limits-file ./fixtures/widget-rate-limits.json --circuit-breaker-file ./fixtures/widget-circuit-breaker.json --yes

Input file: ./fixtures/widget-rate-limits.json (json).

json
{
  "otpRequests": {
    "perWidget": {
      "perMinute": 30
    }
  }
}

Input file: ./fixtures/widget-circuit-breaker.json (json).

json
{
  "floodThresholds": {
    "perMinute": 20,
    "per5Minutes": 60,
    "per15Minutes": 120
  },
  "suspensionSeconds": {
    "firstViolation": 60,
    "secondViolation": 300,
    "maxViolation": 1800
  }
}

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "89abcdef0123456789abcdef",
    "name": "Example OTP",
    "active": false,
    "type": "Test",
    "updatedAt": "2030-03-12T09:00:00.000Z"
  }
}

Prerequisites: an authorized CLI login, an existing gateway integration, and its attached screens. Check the API version and attachment list first; screen settings are refused for headless integrations.

The files use screen rate-limit and circuit-breaker input shapes. The CLI reads and revision-checks resources, then applies the supplied settings across attached screens. If a later screen write fails, the command can return PARTIAL_UPDATE; inspect every applied and notApplied resource before retrying.

The rate ceiling is for OTP requests per individual screen. Circuit-breaker durations are supplied in seconds. After success, inspect the integration and attached screens to confirm each resource's state.

Additional command forms

sh
akedly integrations update <id> --status active --yes
sh
akedly integrations update <id> --status inactive --yes
sh
akedly integrations update <id> --redirect-url https://example.invalid/done --webhook-url https://example.invalid/webhook --yes
sh
akedly integrations update <id> --webhook-url none --yes
sh
akedly integrations update <id> --cluster-gate on --cluster-gate-position balanced --yes
sh
akedly integrations update <id> --verification-methods whatsapp,sms,email --method-order custom --yes
sh
akedly integrations update <id> --circuit-breaker on --circuit-breaker-sensitivity balanced --yes
sh
akedly integrations update <id> --cluster-gate-home-countries EG,SA --yes
sh
akedly integrations update <id> --cluster-gate-home-countries none --yes
sh
akedly integrations update <id> --cluster-gate-home-countries EG,SA --dry-run
sh
akedly integrations update <id> --otp-template <templateId> --yes
sh
akedly integrations update <id> --otp-template default --yes
sh
akedly integrations update <id> --pow-starting-difficulty adaptive --yes
sh
akedly integrations update <id> --pow-auto-scaling off --pow-starting-difficulty 4 --yes
sh
akedly integrations update <id> --passkey-theme dark --yes
sh
akedly integrations update <id> --turnstile on --turnstile-platform web --turnstile-site-key <site-key> --turnstile-secret-key-file <private-file> --turnstile-test-token <fresh-token> --yes
sh
akedly integrations update <id> --circuit-breaker on --pow-starting-difficulty 4 --yes
sh
akedly integrations update <id> --webhook-channels-resolved off --webhook-channels-updated on --webhook-delivery-receipts off --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

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Protected linked-resource writes can be partial; honor PARTIAL_UPDATE details and inspect each named resource before retrying.

Only supplied webhook choices are patched, including off:false; omitted choices keep their saved or unset state. An unset legacy choice uses server version defaults (legacy/headless channel events on and delivery receipts off; gateway all three off). Receipt-only changes need no planning read. Utility updates rely on server rejection.

Own recovery guidance

CodeHint
TEMPLATE_NOT_APPROVEDRun akedly whatsapp otp-templates list and check approval for the integration language before attaching the template.
TEMPLATE_PIPELINE_REQUIRES_WHATSAPPEnable WhatsApp with --verification-methods before attaching a custom OTP template, or use --otp-template default.
API_VERSION_CHANGE_NOT_ALLOWEDOnly headless to gateway is supported. Keep the current API version or create a separate integration for another version. A live gateway requires both --redirect-url and --webhook-url.
PIPELINE_POW_INVALIDUse --pow-starting-difficulty adaptive or a whole number from 2 to 7. This sets the starting difficulty; Akedly controls whether integration PoW is enabled.
PASSKEY_BRANDING_INVALIDUse an HTTPS logo, a company name of at most 100 characters, six-digit #RRGGBB colours and light, dark or system for the theme. Use none to restore a company default.
TURNSTILE_DOMAINS_NOT_EDITABLE--turnstile-allowed-domains is only for an enabled existing legacy Web integration. Manage customer-owned integration hostnames in Cloudflare.
SCREEN_NOT_ALLOWED_ON_V12This integration has gateway screens, so --api-version cannot make it V1.2 (headless). Keep its API version; to build your own screens, create a separate headless integration with akedly integrations create --type headless.

Common error guidance.

integrations delete

Remove an integration that should no longer accept verification traffic.

When to use

  • Use only after confirming no application or screen depends on it.

How it works

  1. Requests deletion after explicit confirmation; dry-run reports the planned operation without deleting.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

The integration is deleted; the response contains the deleted integration under data and a confirmation message at the root.

Next steps

  • Remove references from applications and any screens before running this irreversible action.

Usage

sh
akedly integrations delete <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations delete" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Required positional argument.

Flags

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

Authentication, permission and guards

Auth: login. Permission: pipelines:delete.

Server request: DELETE /pipelines/id/:id.

Shared server-guard guidance.

Consent

--yes. --dry-run bypasses confirmation where supported. Destructive: true. 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

Delete an integration. Read it first to check hasAttachedWidget; deletion has no attachment check. An integration that was upgraded (data.upgrade.to in akedly integrations get) is hidden and turned off instead: its keys stop working at once and its verification history, analytics and billing stay; it then no longer appears in lists and cannot be read, changed or upgraded again.

Login 429 guidance.

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 integrations delete workflow

Remove an integration that should no longer accept verification traffic.

sh
akedly integrations delete 0123456789abcdef01234567 --yes

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "0123456789abcdef01234567",
    "name": "Example OTP",
    "active": false,
    "type": "Test",
    "securityConfig": {
      "apiVersion": "v1.2"
    }
  },
  "message": "Pipeline deleted successfully"
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Additional command forms

sh
akedly integrations delete <id> --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

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Common error guidance.

integrations billing-status

Check the billing eligibility and status information used when deciding whether an integration can process paid verification traffic.

When to use

  • Use when an integration send is blocked by billing or during account setup.

How it works

  1. Reads the account billing-status endpoint.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

Server billing-status object.

Next steps

  • Resolve any account billing requirement shown by the response before sending.

Usage

sh
akedly integrations billing-status

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations billing-status" --output json

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: pipelines:read.

Server request: GET /pipelines/billing-status/:userID.

Owner parameters resolved from the CLI Login: userID.

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

Read billing status for your account integrations.

Login 429 guidance.

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 integrations billing-status workflow

Check the billing eligibility and status information used when deciding whether an integration can process paid verification traffic.

sh
akedly integrations billing-status

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "user": {
      "_id": "0123456789abcdef01234567",
      "billingMode": "PPM",
      "resolvedBillingMode": "PPM",
      "resolvedSource": "user"
    },
    "billingPlan": {
      "_id": "89abcdef0123456789abcdef",
      "name": "Example plan",
      "billingMode": "PPM",
      "resolvedBillingMode": "PPM",
      "resolvedSource": "plan"
    },
    "pipelines": [
      {
        "_id": "fedcba987654321001234567",
        "name": "Example OTP",
        "billingMode": null,
        "resolvedBillingMode": "PPM",
        "resolvedSource": "plan"
      }
    ]
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Additional command forms

sh
akedly integrations billing-status

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

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Common error guidance.

integrations active-billing-status

Check billing readiness for currently active integrations before a rollout.

When to use

  • Use when confirming which active integrations have usable billing status.

How it works

  1. Reads the active-integration billing summary.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

Server billing status summary.

Next steps

  • Review inactive or unready integrations separately with integrations get and billing-status.

Usage

sh
akedly integrations active-billing-status

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations active-billing-status" --output json

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: pipelines:read.

Server request: GET /pipelines/active-billing-status/:userID.

Owner parameters resolved from the CLI Login: userID.

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

Read billing status for the first active live integration.

Login 429 guidance.

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 integrations active-billing-status workflow

Check billing readiness for currently active integrations before a rollout.

sh
akedly integrations active-billing-status

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "user": {
      "_id": "0123456789abcdef01234567",
      "billingMode": "PPM",
      "resolvedBillingMode": "PPM",
      "resolvedSource": "user"
    },
    "billingPlan": {
      "_id": "89abcdef0123456789abcdef",
      "name": "Example plan",
      "billingMode": "PPM",
      "resolvedBillingMode": "PPM",
      "resolvedSource": "plan"
    },
    "pipeline": {
      "_id": "fedcba987654321001234567",
      "name": "Example OTP",
      "active": true,
      "type": "Live",
      "billingMode": null,
      "resolvedBillingMode": "PPM",
      "resolvedSource": "plan"
    }
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Additional command forms

sh
akedly integrations active-billing-status

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

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Common error guidance.

integrations otp-sms-preview

Preview the actual locale-specific OTP copy and SMS segmentation before configuring an OTP integration.

When to use

  • Use to inspect English or Arabic OTP text without sending a message.

How it works

  1. Renders a synthetic zero-filled code using the configured locale and digit count, applies the current company name or fallback, and returns encoding, characters, segments, and truncation details. It sends no SMS.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

Rendered preview fields returned by the API.

Next steps

  • Review wording and length before enabling the corresponding integration settings.

Usage

sh
akedly integrations otp-sms-preview

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations otp-sms-preview" --output json

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--otp-languageenumen | arCommand-specific option; see the full command details below. Query parameter: locale.
--digitsinteger4 to 6Command-specific option; see the full command details below. Query parameter: digits.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: pipelines:read.

Server request: GET /pipelines/otp-sms-preview.

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

Preview OTP SMS text without sending a message.

Login 429 guidance.

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 integrations otp-sms-preview workflow

Preview the localized OTP SMS copy and digit count before choosing customer-facing message settings.

sh
akedly integrations otp-sms-preview --otp-language en --digits 6

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "locale": "en",
    "otpDigits": 6,
    "appliesTo": "cequens",
    "wouldTruncate": false,
    "segments": 1,
    "encoding": "GSM7",
    "characters": 38,
    "companyName": "Example Co",
    "sample": "000000 is your OTP. Sent by Example Co"
  },
  "message": "OTP SMS preview generated successfully"
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Additional command forms

sh
akedly integrations otp-sms-preview --otp-language en --digits 4

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

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Common error guidance.

integrations pow-policy

See the server’s current proof-of-work policy before configuring abuse protection.

When to use

  • Use when deciding whether PoW thresholds comply with server policy.

How it works

  1. Reads the policy endpoint without changing an integration.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

Policy values returned by the server.

Next steps

  • Use the reported limits when selecting PoW settings.

Usage

sh
akedly integrations pow-policy

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations pow-policy" --output json

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: pipelines:read.

Server request: GET /pipelines/pow-policy.

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

Read the proof-of-work policy.

Login 429 guidance.

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 integrations pow-policy workflow

See the server’s current proof-of-work policy before configuring abuse protection.

sh
akedly integrations pow-policy

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "minDifficulty": 3,
    "defaultDifficulty": 4,
    "maxDifficulty": 6
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Additional command forms

sh
akedly integrations pow-policy

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

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Common error guidance.

integrations rate-recommendations

Estimate safer integration rate limits from observed traffic before applying limits.

When to use

  • Use when tuning an owned non-system integration; recommendations require enough analysed traffic and confidence.

How it works

  1. Requests an analysis for the selected period or custom date range; this command only returns recommendations.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

Analysis result, including readiness/confidence and suggested settings when available.

Next steps

  • Apply only after reviewing recommendations with integrations update; low traffic returns no ready settings.

Usage

sh
akedly integrations rate-recommendations <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations rate-recommendations" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Required positional argument.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--periodenumlast-month | last-quarter | last-6-monthsCommand-specific option; see the full command details below. Manifest body field: period.
--start-datetext—Command-specific option; see the full command details below. Manifest body field: customDateRange.sDate.
--end-datetext—Command-specific option; see the full command details below. Manifest body field: customDateRange.eDate.
--dry-runboolean switch—Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: pipelines:update.

Server request: POST /pipeline-rate-recommendations/:pipelineID.

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

Read rate recommendations. Requires Full access; dates use server-local-day semantics.

Login 429 guidance.

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 integrations rate-recommendations workflow

Estimate safer integration rate limits from observed traffic before applying limits.

sh
akedly integrations rate-recommendations 0123456789abcdef01234567 --period last-month

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "applyReady": {
      "enoughTraffic": true,
      "confidence": "high",
      "analysedRequests": 250,
      "settings": {
        "rateLimiting": {
          "perPipeline": {
            "perMinute": 30,
            "perHour": 600,
            "perDay": 3000
          }
        }
      }
    }
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Additional command forms

sh
akedly integrations rate-recommendations <id> --period last-month

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

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Common error guidance.

integrations dev-mode show

Inspect whether an integration currently has the development test-pair mode and bypasses enabled.

When to use

  • Use before testing with the Developer mode test number or diagnosing why a test bypass is unavailable.

How it works

  1. Reads Developer mode configuration for the integration.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

Current dev-mode settings.

Next steps

  • Use dev-mode set to change settings; test-pair flows are synthetic and are not production verification.

Usage

sh
akedly integrations dev-mode show <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations dev-mode show" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Required positional argument.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: pipelines:dev_mode.

Server request: GET /pipelines/id/:id/dev-mode.

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

Read Developer mode and its disposable test number and code. Requires Full access.

Login 429 guidance.

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 integrations dev-mode show workflow

Inspect whether an integration currently has the development test-pair mode and bypasses enabled.

sh
akedly integrations dev-mode show 0123456789abcdef01234567

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "enabled": false
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Additional command forms

sh
akedly integrations dev-mode show <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

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Common error guidance.

integrations dev-mode set

Enable or disable the integration’s development test-pair behavior and permitted Turnstile/PoW bypasses.

When to use

  • Use for controlled development testing after confirming the integration is the intended test integration.

How it works

  1. Requires confirmation for writes; dry-run previews. Bypasses only affect eligible development test-pair traffic.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

Saved development-mode settings.

Next steps

  • Run a test-pair flow and turn development mode off when finished.

Usage

sh
akedly integrations dev-mode set <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations dev-mode set" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Required positional argument.

Flags

FlagTypeEnum / rangeRequiredDescription
--ksaboolean switch—noSelect the KSA deployment.
--dev-modeenumon | offyesCommand-specific option; see the full command details below. Manifest body field: enabled. Tip: Do not leave Developer mode on for production traffic: while the window is open, anyone who knows the test number and code can complete a verification for that number.
--bypass-turnstileenumon | offnoCommand-specific option; see the full command details below. Manifest body field: bypassTurnstile. Tip: On headless integrations, use Bypass Turnstile for testing from localhost instead of adding localhost in Cloudflare: when it is on, while the Developer mode window is open, it skips Turnstile for every request to the integration, so never turn it on for an integration serving production traffic.
--bypass-powenumon | offnoCommand-specific option; see the full command details below. Manifest body field: bypassPoW. Tip: On headless integrations, keep Bypass PoW off unless proof-of-work blocks your tests: when it is on, while the Developer mode window is open, it skips the check for every request to the integration, not only the test number. It stops working when the window ends or Developer mode is turned off.
--dev-mode-digitsinteger4 to 6noCommand-specific option; see the full command details below. Manifest body field: digits.
--dry-runboolean switch—noPreview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--yesboolean switch—noConfirm this action where consent is required.
--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: login. Permission: pipelines:dev_mode.

Server request: PUT /pipelines/id/:id/dev-mode.

Shared server-guard guidance.

Consent

--yes. --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

Set the one-hour Developer mode window for headless. Enabling while already on does not extend the hour; disable and re-enable for a fresh hour and a new test number and code. When enabling, omitted bypass flags reset to off. The server returns a disposable test number and code without sending anything. Developer mode loosens live verification on this integration (it bypasses rate limiting and circuit breaker), so every change here needs --yes, turning it off included; --dry-run previews without --yes.

Login 429 guidance.

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 integrations dev-mode set workflow

Enable or disable the integration’s development test-pair behavior and permitted Turnstile/PoW bypasses.

sh
akedly integrations dev-mode set 0123456789abcdef01234567 --dev-mode on --yes

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "0123456789abcdef01234567",
    "name": "Example OTP",
    "active": false,
    "type": "Test",
    "devMode": {
      "enabled": true,
      "bypassTurnstile": true,
      "bypassPoW": true
    },
    "updatedAt": "2030-03-12T09:00:00.000Z"
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Additional command forms

sh
akedly integrations dev-mode set <id> --dev-mode on --dev-mode-digits 4 --yes
sh
akedly integrations dev-mode set <id> --dev-mode off --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

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Common error guidance.

integrations webhook-secret reveal

Recover the current webhook signing secret while it remains unacknowledged; the reveal operation can be repeated until acknowledgement.

When to use

  • Use before acknowledgement to recover the current secret when needed; repeated reveal calls continue to return it until acknowledged.

How it works

  1. Reads the current secret. Reveal does not consume or acknowledge it; only the acknowledgement command closes this reveal window. With --secret-file, the CLI removes the secret field from JSON and writes it privately; without it, JSON contains the secret.

Prerequisites

  • A CLI login with permission for this account and resource.
  • For secret-safe machine output, choose a new private --secret-file path; omitting it places webhookSigningSecret in the JSON response.

Expected outcome

The current webhook signing secret. A private file sink returns secretFile without the secret; without --secret-file the secret is present in JSON.

Next steps

  • Store the file in a secret manager; do not paste it into logs.

Usage

sh
akedly integrations webhook-secret reveal <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations webhook-secret reveal" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Required positional argument.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--secret-filetext—Write the secret to a new mode 0600 file and omit it from output; an existing path is refused.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: pipelines:update.

Server request: GET /pipelines/id/:id/webhook-secret.

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

Sensitive output: secret-sink. Use the supported sink; default output may contain a secret. Supported sinks: --secret-file.

Full command details

Reveal the webhook signing secret until acknowledged. Use --secret-file to suppress it from output.

Login 429 guidance.

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 integrations webhook-secret reveal workflow

Recover the current unacknowledged secret and write it to a private file; the reveal can be repeated until acknowledged.

sh
akedly integrations webhook-secret reveal 0123456789abcdef01234567 --secret-file ./private/webhook-secret.txt

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "secretFile": "./private/webhook-secret.txt"
  },
  "message": "Copy this secret now — it will not be shown again until you regenerate"
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Secret output sink: ./private/webhook-secret.txt. Use a new private path when running the command; the synthetic example is documentation only.

Additional command forms

sh
akedly integrations webhook-secret reveal <id> --secret-file <new path>

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

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Without --secret-file, the CLI passes through the webhookSigningSecret in JSON. Use a private --secret-file to keep secret bytes out of stdout.

Common error guidance.

integrations webhook-secret regenerate

Rotate a compromised or lost webhook signing secret, invalidating the previous secret immediately.

When to use

  • Use only when ready to deploy the replacement to the webhook receiver.

How it works

  1. Rotates the current secret, invalidating the previous value. With --secret-file, the CLI removes the secret field from JSON and writes it privately; without it, JSON contains the secret. Acknowledge after the replacement has been safely captured.

Prerequisites

  • A CLI login with permission for this account and resource.
  • For secret-safe machine output, choose a new private --secret-file path; omitting it places webhookSigningSecret in the JSON response.

Expected outcome

A newly rotated webhook signing secret. A private file sink returns secretFile without the secret; without --secret-file the secret is present in JSON.

Next steps

  • Deploy the replacement secret, then acknowledge it; until deployment, signed webhook verification using the old secret will fail.

Usage

sh
akedly integrations webhook-secret regenerate <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations webhook-secret regenerate" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Required positional argument.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--secret-filetext—Write the secret to a new mode 0600 file and omit it from output; an existing path is refused.
--yesboolean switch—Confirm this action where consent is required.
--dry-runboolean switch—Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: pipelines:update.

Server request: POST /pipelines/id/:id/webhook-secret/regenerate.

Shared server-guard guidance.

Consent

--yes. --dry-run bypasses confirmation where supported. Destructive: true. 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: secret-sink. Use the supported sink; default output may contain a secret. Supported sinks: --secret-file.

Full command details

Rotate the webhook signing secret; the old secret stops immediately. Save the new secret before acknowledging it. The new secret is printed by default; prefer --secret-file <new path> to save it privately instead.

Login 429 guidance.

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 integrations webhook-secret regenerate workflow

Rotate a compromised or lost webhook signing secret, invalidating the previous secret immediately.

sh
akedly integrations webhook-secret regenerate 0123456789abcdef01234567 --yes --secret-file ./private/webhook-secret.txt

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "secretFile": "./private/webhook-secret.txt"
  },
  "message": "Webhook signing secret regenerated successfully. Update your server immediately."
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Secret output sink: ./private/webhook-secret.txt. Use a new private path when running the command; the synthetic example is documentation only.

Additional command forms

sh
akedly integrations webhook-secret regenerate <id> --yes --secret-file <new path>

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

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Without --secret-file, the CLI passes through the webhookSigningSecret in JSON. Use a private --secret-file to keep secret bytes out of stdout.

Common error guidance.

integrations webhook-secret acknowledge

Confirm that the replacement webhook secret has been securely captured, allowing the secret lifecycle to be closed.

When to use

  • Use after saving a newly issued or revealed secret; supply either the saved secret file or its exact final four characters.

How it works

  1. Sends only the secret suffix for server-side acknowledgement; confirmation required.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

Acknowledgement result without returning secret material.

Next steps

  • Keep the saved secret in the webhook receiver’s secret store.

Usage

sh
akedly integrations webhook-secret acknowledge <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations webhook-secret acknowledge" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Required positional argument.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--secret-filetext—Command-specific option; see the full command details below. Manifest body field: secretSuffix.
--secret-suffixtext—Command-specific option; see the full command details below. Manifest body field: secretSuffix.
--yesboolean switch—Confirm this action where consent is required.
--dry-runboolean switch—Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: pipelines:update.

Server request: POST /pipelines/id/:id/webhook-secret/acknowledge.

Shared server-guard guidance.

Consent

--yes. --dry-run bypasses confirmation where supported. Destructive: true. 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

Acknowledge holding the secret using exactly one file or four-character suffix. After acknowledgement reveal is refused.

Login 429 guidance.

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 integrations webhook-secret acknowledge workflow

Confirm that the replacement webhook secret has been securely captured, allowing the secret lifecycle to be closed.

sh
akedly integrations webhook-secret acknowledge 0123456789abcdef01234567 --secret-suffix AQE= --yes

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "message": "Secret acknowledged"
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Synthetic acknowledge from the saved webhook-secret file

Confirm that the replacement webhook signing secret was saved so its rotation can be acknowledged.

sh
akedly integrations webhook-secret acknowledge 0123456789abcdef01234567 --secret-file ./fixtures/saved-webhook-secret.txt --yes

Input file: ./fixtures/saved-webhook-secret.txt (text).

text
[REDACTED — use your privately saved secret file]

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "message": "Secret acknowledged"
}

Prerequisites: an authorized CLI login and the exact saved secret file for this integration. The CLI sends only the file's final four characters for acknowledgement; it does not return a data object.

Secret fixture content is synthetic and must be redacted from any rendered human guide. Keep the real saved secret in the webhook receiver's secret store. Acknowledgement confirms capture; it does not revoke or consume the saved value.

Additional command forms

sh
akedly integrations webhook-secret acknowledge <id> --secret-file <saved path> --yes
sh
akedly integrations webhook-secret acknowledge <id> --secret-suffix <last 4 characters> --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

The success response contains status and message only; it has no data field.

Common error guidance.

integrations webhook-test preview

Inspect the payload and signing headers Akedly would use for a selected test webhook event.

When to use

  • Use to inspect the supported event list, generated signature-header placeholders and synthetic payload before testing a receiver.

How it works

  1. Builds a preview from the owned integration and requested event; read-only.

Prerequisites

  • An existing owned integration with an allowed test event for its API version and product; a configured Server URL is needed for the later run, not the preview.

Expected outcome

Preview payload and headers returned by the API.

Next steps

  • Check that the receiver accepts the event shape before using webhook-test run.

Usage

sh
akedly integrations webhook-test preview <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations webhook-test preview" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Required positional argument.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--eventtext—Command-specific option; see the full command details below. Query parameter: event.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: pipelines:read.

Server request: GET /pipelines/id/:id/webhook-test/preview.

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

Preview the sample webhook payload and placeholder signing headers.

Login 429 guidance.

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 integrations webhook-test preview workflow

Inspect the payload and signing headers Akedly would use for a selected test webhook event.

sh
akedly integrations webhook-test preview 0123456789abcdef01234567 --event verification

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "event": "verification",
    "events": [
      "verification"
    ],
    "method": "POST",
    "url": "https://receiver.example.invalid/hooks/akedly",
    "headers": {
      "Content-Type": "application/json",
      "User-Agent": "Akedly-Webhook/1.0",
      "svix-id": "msg_•••••• (generated)",
      "svix-timestamp": "•••••••••• (generated)",
      "svix-signature": "v1,•••••• (generated)"
    },
    "body": {
      "event": "webhook.test",
      "test": true,
      "mainTransaction": {
        "transactionID": "tx_example_001",
        "status": "Successful",
        "verificationAddress": {
          "phoneNumber": "+201234567890"
        },
        "OTP": "123456",
        "resolvedChannel": "whatsapp",
        "channels": [
          "whatsapp"
        ],
        "isTest": false,
        "userID": "0123456789abcdef01234567",
        "pipelineID": "89abcdef0123456789abcdef",
        "creationDate": "2030-03-12T08:57:00.000Z",
        "expirationDate": "2030-03-12T09:01:00.000Z",
        "updateDate": "2030-03-12T09:00:00.000Z",
        "verificationMethod": "Whatsapp"
      },
      "transactionReq": {
        "_id": "fedcba987654321001234567",
        "mainTransactionID": "tx_example_001",
        "status": "Successful",
        "isTest": false,
        "channels": [
          "whatsapp"
        ],
        "sentVerificationDate": "2030-03-12T08:57:00.000Z",
        "inputOTP": "123456",
        "verificationDate": "2030-03-12T09:00:00.000Z",
        "creationDate": "2030-03-12T08:57:00.000Z",
        "expirationDate": "2030-03-12T09:01:00.000Z",
        "verificationMethod": "Whatsapp"
      }
    }
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Additional command forms

sh
akedly integrations webhook-test preview <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

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

The sample payload contains synthetic transaction and OTP values; actual previews are generated from a synthetic test transaction and vary by integration version/product.

Common error guidance.

integrations webhook-test run

Send a signed test event to the integration’s configured webhook URL to verify receiver connectivity.

When to use

  • Use after previewing the event and confirming the configured URL is a safe test receiver.

How it works

  1. Requires explicit confirmation; this makes an outbound webhook request and can trigger receiver-side effects.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

Delivery attempt result returned by the server.

Next steps

  • Inspect receiver logs and delivery result; avoid automatic retries if the outcome is ambiguous.

Usage

sh
akedly integrations webhook-test run <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations webhook-test run" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Required positional argument.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--eventtext—Command-specific option; see the full command details below. Manifest body field: event.
--yesboolean switch—Confirm this action where consent is required.
--dry-runboolean switch—Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: pipelines:update.

Server request: POST /pipelines/id/:id/webhook-test.

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: echo-scrub. echo-scrub masks secret-shaped text, credential fields, secret query parameters and JSON secret fields inside strings in the response, such as a webhook receiver echo or BYO-SMS steps; keep the output private anyway.

Full command details

Send a signed sample to the configured Server URL. Exit 0 means the request ran; read the top-level delivered (false on delivery failure), statusCode, error and tip. Secret-shaped text in any response string is shown as [REDACTED].

Login 429 guidance.

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 integrations webhook-test run workflow

Send a signed test event to the integration’s configured webhook URL to verify receiver connectivity.

sh
akedly integrations webhook-test run 0123456789abcdef01234567 --event verification --yes

Illustrative response (sensitive values omitted):

json
{
  "delivered": true,
  "statusCode": 200,
  "durationMs": 12,
  "error": null,
  "tip": null,
  "request": {
    "method": "POST",
    "url": "https://receiver.example.invalid/hooks/akedly",
    "headers": {
      "Content-Type": "application/json",
      "User-Agent": "Akedly-Webhook/1.0",
      "svix-id": "msg_fixture_001",
      "svix-timestamp": "1890000000",
      "svix-signature": "v1,AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
    },
    "body": {
      "event": "webhook.test",
      "test": true,
      "mainTransaction": {
        "transactionID": "tx_example_001",
        "status": "Successful",
        "verificationAddress": {
          "phoneNumber": "+201234567890"
        },
        "OTP": "123456",
        "resolvedChannel": "whatsapp",
        "channels": [
          "whatsapp"
        ],
        "isTest": false,
        "userID": "0123456789abcdef01234567",
        "pipelineID": "89abcdef0123456789abcdef",
        "creationDate": "2030-03-12T08:57:00.000Z",
        "expirationDate": "2030-03-12T09:01:00.000Z",
        "updateDate": "2030-03-12T09:00:00.000Z",
        "verificationMethod": "Whatsapp"
      },
      "transactionReq": {
        "_id": "fedcba987654321001234567",
        "mainTransactionID": "tx_example_001",
        "status": "Successful",
        "isTest": false,
        "channels": [
          "whatsapp"
        ],
        "sentVerificationDate": "2030-03-12T08:57:00.000Z",
        "inputOTP": "123456",
        "verificationDate": "2030-03-12T09:00:00.000Z",
        "creationDate": "2030-03-12T08:57:00.000Z",
        "expirationDate": "2030-03-12T09:01:00.000Z",
        "verificationMethod": "Whatsapp"
      }
    }
  },
  "response": {
    "body": "accepted"
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

This operation contacts the configured webhook receiver; the synthetic example is not to be executed.

The receiver URL must be configured on the existing integration. This command contacts it; the sample must not be executed.

Additional command forms

sh
akedly integrations webhook-test run <id> --yes
sh
akedly integrations webhook-test run <id> --yes --fields delivered,statusCode,error,tip

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

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Delivery failures are HTTP 200 command results with delivered:false; statusCode and response.body can be null. Inspect error and tip before deciding whether to retry.

The request snapshot includes the synthetic test payload and signed headers. Actual timestamps, IDs and signatures are generated per run.

Common error guidance.

integrations test-challenge

Fetch a fresh challenge for the dashboard test-send flow without sending an OTP.

When to use

  • Use immediately before a dashboard test send that requires PoW or Turnstile challenge data.

How it works

  1. Reads a fresh headless challenge for the chosen integration.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

Challenge token, difficulty, expiry, algorithm and Turnstile requirement as returned by the API.

Next steps

  • Pass the fresh challenge through the test-send flow; do not reuse expired challenge data.

Usage

sh
akedly integrations test-challenge

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations test-challenge" --output json

Flags

FlagTypeEnum / rangeRequiredDescription
--ksaboolean switch—noSelect the KSA deployment.
--integration-idid—yesCommand-specific option; see the full command details below. Query parameter: pipelineID.
--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: login. Permission: sandbox:execute.

Server request: GET /api/v1.2/transactions/dashboard/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 headless dashboard PoW challenge. Requires a Full access CLI Login with sandbox:execute and a usable account API key; Read-only logins and logins approved by Akedly staff without full access are refused. First enable Developer mode explicitly with integrations dev-mode set <id> --dev-mode on --yes and use the returned fake test number, valid for about an hour. Test commands never enable Developer mode or bypass flags.

Login 429 guidance.

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 integrations test-challenge workflow

Fetch a fresh challenge for the dashboard test-send flow without sending an OTP.

sh
akedly integrations test-challenge --integration-id 0123456789abcdef01234567

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "challengeRequired": true,
    "challengeToken": "synthetic-token",
    "challenge": "synthetic-challenge",
    "difficulty": 2,
    "expiresAt": "2030-03-12T09:05:00.000Z",
    "algorithm": "sha256",
    "turnstile": {
      "required": false,
      "siteKey": null
    }
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Additional command forms

sh
akedly integrations test-challenge --integration-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

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Common error guidance.

integrations test-send

Send a dashboard test OTP to validate the integration and recipient path.

When to use

  • Use only with an authorized test destination and explicit confirmation; a real SMS/WhatsApp delivery may incur provider cost.

How it works

  1. Fetches a fresh challenge, solves PoW where required, then sends once; ambiguous POST outcomes are not automatically retried.

Prerequisites

  • An existing headless OTP integration owned by the logged-in account.
  • An authorized test destination; this command sends an OTP and may incur provider cost.

Expected outcome

Transaction IDs for the send request.

Next steps

  • Check delivery and use test-verify with the transaction request ID if verifying the code.

Usage

sh
akedly integrations test-send

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations test-send" --output json

Flags

FlagTypeEnum / rangeRequiredDescription
--ksaboolean switch—noSelect the KSA deployment.
--integration-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.
--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: login. Permission: sandbox:execute.

Server request: POST /api/v1.2/transactions/dashboard/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. Requires --yes and a Full access CLI Login with sandbox:execute and a usable account API key; Read-only logins and logins approved by Akedly staff without full access are refused. The send is real and billed unless the number is the integration's Developer mode test number. For a free test, first run akedly integrations dev-mode set <id> --dev-mode on --yes and send to the test number it returns (valid for about an hour). This command never enables Developer mode or bypass flags. An ambiguous failure may have sent a message; check the destination before retrying. Dry runs send nothing and need no CLI Login.

Login 429 guidance.

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 integrations test-send workflow

Send a dashboard test OTP to validate the integration and recipient path.

sh
akedly integrations test-send --integration-id 0123456789abcdef01234567 --phone-number +201234567890 --yes

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "transactionID": "tx_example_001",
    "transactionReqID": "89abcdef0123456789abcdef"
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

This operation sends an OTP and may incur cost; the synthetic example is not to be executed.

Additional command forms

sh
akedly integrations test-send --integration-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

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Common error guidance.

integrations test-verify

Complete a headless dashboard test verification by checking the OTP against its transaction request.

When to use

  • Use only after a headless dashboard test-send has returned a transactionReqID and the test code is available.

How it works

  1. Checks transaction ownership for the logged-in account, then calls the headless secure OTP verifier. A successful response returns verified, transactionID and frontendCallbackURL, and may include enrollmentToken for eligible phone verification.

Prerequisites

  • A transactionReqID returned by a headless dashboard test-send for this account, plus the received test OTP.

Expected outcome

Transaction request status returned by the API.

Next steps

  • Check the final status; if expired or failed, begin a new test-send.

Usage

sh
akedly integrations test-verify <transactionReqID>

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations test-verify" --output json
PositionalGrammarUsage guidance
<transactionReqID>^[a-fA-F0-9]{24}$transactionReqID must be a 24-hex transaction request id.

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: login. Permission: sandbox:execute.

Server request: POST /api/v1.2/transactions/dashboard/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 dashboard headless transaction using a Full access CLI Login with sandbox:execute; Read-only logins and logins approved by Akedly staff without full access are refused. Successful verification can fire the configured backend webhook; responses can include live OTP fields, so keep output private.

Login 429 guidance.

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 integrations test-verify workflow

Verify an OTP from a dashboard test-send transaction.

sh
akedly integrations test-verify 89abcdef0123456789abcdef --otp 123456

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "verified": true,
    "transactionID": "tx_example_001",
    "frontendCallbackURL": "https://app.example.invalid/verified"
  },
  "message": "OTP verified successfully"
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Additional command forms

sh
akedly integrations test-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

This command uses the headless dashboard verification endpoint. The success DTO contains verified, transactionID and frontendCallbackURL; enrollmentToken may be present for eligible phone verifications.

Common error guidance.

integrations sandbox-demo ensure

Provision or retrieve the account’s isolated sandbox demo integration and associated demo resources.

When to use

  • Use for a sandbox walkthrough when a demo setup is needed; it is not a production integration.

How it works

  1. Ensures demo resources for the requested API version; repeated calls converge on the sandbox setup.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

The ensured demo version, a safe integration projection, and either widget:null (headless) or an ensured screen projection (gateway).

Next steps

  • For headless, use the direct API demo flow. For gateway, inspect the returned screen, then finish gateway screen setup as required; provisioning does not by itself complete a production embed.

Usage

sh
akedly integrations sandbox-demo ensure

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations sandbox-demo ensure" --output json

Flags

FlagTypeEnum / rangeRequiredDescription
--ksaboolean switch—noSelect the KSA deployment.
--api-versionenumv1.2 | v2yesCommand-specific option; see the full command details below. Manifest body field: version. Tip: Use v2 (gateway) if you will embed Akedly's hosted screen, and v1.2 (headless) if you will build the verification screens yourself or cannot embed an iframe or open a system browser. v1 (legacy) sunsets on December 30, 2026.
--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: login. Permission: sandbox:execute.

Server request: POST /pipelines/sandbox-demo/ensure.

Shared server-guard guidance.

Consent

--yes. --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

Ensure the signed-in account's OTP sandbox demo resources with --api-version v1.2|v2 --yes (--version prints the CLI package version). Requires a Full access CLI Login with sandbox:execute and pipelines:create; gateway also requires widgets:create. Read-only logins are refused. This can adopt your existing unmarked OTP integration (or an older integration with no product) named exactly "Sandbox Demo Pipeline" (for v1.2) or "Sandbox Widget Pipeline" (for v2) and the same API version and, for gateway, an unmarked screen attached to it (one named "Sandbox Widget" first), or reattach a demo screen whose integration was deleted. Each run resets the demo integration's API version and, for gateway, both the Return URL and the Server URL, so Return URL and Server URL changes made with integrations update do not persist. These writes need only the permissions above, not pipelines:update or widgets:update; --yes confirms them. New demo integrations are active Test integrations. Gateway Return URLs and Server URLs point to the environment's dashboard /admin and API /sandbox-webhook-sink. The API does not serve /sandbox-webhook-sink yet, so this Server URL is not a working demo webhook receiver; test your own handler with akedly integrations webhook-test run <id> --yes on your own integration instead. This is separate from akedly utilities sandbox status/send and prepares OTP resources without sending, charging or enabling Developer mode. Next for v1.2: run akedly integrations dev-mode set <id> --dev-mode on --yes (needs pipelines:dev_mode), then akedly integrations test-send --integration-id <id> --phone-number <test number> --yes, then akedly integrations test-verify <transactionReqID> --otp <test code>, using data.transactionReqID from test-send. Use the current returned data.devMode.testPair phoneNumber and otp from dev-mode set while that window is active; only this test number is free. test-send needs sandbox:execute and a usable server-selected account API key; any other number is a real, billed send. Inspect the returned integration id, name, API version, channel and server-reported devMode enabled/expiresAt; an enabled window can already be expired. Gateway also returns screen id/publicKey, without its Secret. Reused or adopted integrations and screens keep their current active state and status, which the response does not show (reused screens are not reactivated); check them with akedly integrations get <id> and akedly integrations screens get <id>; reactivate with akedly integrations update <id> --status active --yes or akedly integrations screens update <id> --status active --yes. No test number, Return URL, Server URL, secrets or authentication URL are returned. This prepared gateway demo is not a complete gateway setup: open the demo gateway integration in the dashboard and choose Test now. Its sandbox launch requires an allowed dashboard Origin and session; the screen Secret is not returned here. Set screen Developer mode with akedly integrations screens update <id> --dev-mode on --yes (needs widgets:update), and read its current test number and code at data.devMode.testPair with akedly integrations screens get <id>. Resources can remain partly prepared after failure: repeat this command with the same --api-version to converge, except after a SANDBOX_PIPELINE_PURPOSE_CONFLICT or SANDBOX_WIDGET_PURPOSE_CONFLICT, which repeating will not fix; do not automatically delete them. Run akedly integrations list first to inspect possible same-name adoption; dry-run does not inspect existing resources. Dry-run validates and previews offline without consent, credentials or requests.

Login 429 guidance.

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 integrations sandbox-demo ensure workflow

Provision or retrieve the account’s isolated sandbox demo integration and associated demo resources.

sh
akedly integrations sandbox-demo ensure --api-version v1.2 --yes

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "version": "v1.2",
    "pipeline": {
      "_id": "0123456789abcdef01234567",
      "name": "Sandbox Demo Pipeline",
      "apiVersion": "v1.2",
      "channel": "whatsapp",
      "devMode": {
        "enabled": false
      }
    },
    "widget": null
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Additional command forms

sh
akedly integrations sandbox-demo ensure --api-version v1.2 --yes
sh
akedly integrations sandbox-demo ensure --api-version v2 --yes
sh
akedly integrations sandbox-demo ensure --api-version v2 --dry-run

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

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Own recovery guidance

CodeHint
INVALID_SANDBOX_VERSIONUse --api-version v1.2 or --api-version v2; --version prints the CLI package version.
SANDBOX_INDEX_UNAVAILABLESandbox purpose indexes are unavailable. Retry later with the same --api-version or contact Akedly support.
SANDBOX_PIPELINE_PURPOSE_CONFLICTAn incompatible integration holds the demo purpose. Inspect akedly integrations list and ask Akedly support to resolve the conflict before repeating ensure.
SANDBOX_WIDGET_PURPOSE_CONFLICTThe demo screen purpose is attached to another integration. Inspect akedly integrations screens list and akedly integrations screens list --status inactive, and ask Akedly support to resolve the conflict; do not delete resources automatically.
SANDBOX_RESOURCE_CHANGEDA sandbox resource changed during preparation. Repeat akedly integrations sandbox-demo ensure with the same --api-version and --yes.
SANDBOX_ENSURE_FAILEDResources may be partly prepared. Repeat akedly integrations sandbox-demo ensure with the same --api-version and --yes; if it keeps failing, contact Akedly support.

Common error guidance.

zero-verify-bans list

Review phone, email, or device identities currently banned for repeated verification attempts that never completed.

When to use

  • Use to diagnose why a customer identity cannot start another verification.

How it works

  1. Reads bans belonging to the logged-in account, newest first; identity values are sensitive account data.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

Array of ban records with status, rung, dates, mode and lift metadata.

Next steps

  • If the ban is no longer warranted, unban its record ID; otherwise wait for expiry or review the underlying behavior.

Usage

sh
akedly zero-verify-bans list

Inspect this command offline before preparing an operation:

sh
akedly describe "zero-verify-bans list" --output json

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: zero_verify_bans:read.

Server request: GET /zero-verify-bans.

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

List your account zero-verify bans.

Login 429 guidance.

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 zero-verify-bans list workflow

Review phone, email, or device identities currently banned for repeated verification attempts that never completed.

sh
akedly zero-verify-bans list

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": [
    {
      "_id": "0123456789abcdef01234567",
      "identityType": "phone",
      "identityValue": "+201234567890",
      "rung": 1,
      "bannedAt": "2030-03-12T09:00:00.000Z",
      "expiresAt": "2030-03-12T10:00:00.000Z",
      "status": "active",
      "mode": "enforce"
    }
  ]
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Additional command forms

sh
akedly zero-verify-bans list

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

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Common error guidance.

zero-verify-bans unban

Lift one account-owned zero-verify ban and exonerate its associated identity.

When to use

  • Use after confirming the identity should regain access; lifting affects enforcement immediately.

How it works

  1. Requires confirmation, checks ownership/current status, records a manual lift and emits an operational notification.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

Updated ban record with lifted status and timestamp.

Next steps

  • Retry the customer flow after lift; the identity may be banned again if the underlying pattern recurs.

Usage

sh
akedly zero-verify-bans unban <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "zero-verify-bans unban" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Required positional argument.

Flags

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

Authentication, permission and guards

Auth: login. Permission: zero_verify_bans:update.

Server request: PATCH /zero-verify-bans/:id/unban.

Shared server-guard guidance.

Consent

--yes. --dry-run bypasses confirmation where supported. Destructive: true. 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

Lift a zero-verify security ban.

Login 429 guidance.

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 zero-verify-bans unban workflow

Lift one account-owned zero-verify ban and exonerate its associated identity.

sh
akedly zero-verify-bans unban 0123456789abcdef01234567 --yes

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "0123456789abcdef01234567",
    "identityType": "phone",
    "identityValue": "+201234567890",
    "rung": 1,
    "bannedAt": "2030-03-12T09:00:00.000Z",
    "expiresAt": "2030-03-12T10:00:00.000Z",
    "status": "lifted",
    "liftedAt": "2030-03-12T09:30:00.000Z",
    "liftReason": "manual",
    "mode": "enforce"
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Additional command forms

sh
akedly zero-verify-bans unban <id> --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

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Common error guidance.

webhooks verify

Verify locally that a received Akedly webhook’s exact raw body matches its Svix signature and timestamp.

When to use

  • Use in a receiver or incident investigation with the original body bytes, headers and current integration signing secret.

How it works

  1. Reads bounded local files, checks timestamp tolerance, and computes HMAC locally; it sends no network request.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

A valid verdict with timestampAgeSeconds, or a coded local verification error.

Next steps

  • Only parse/process the webhook after valid is true; preserve raw bytes and use the active secret.

Usage

sh
akedly webhooks verify

Inspect this command offline before preparing an operation:

sh
akedly describe "webhooks verify" --output json

Flags

FlagTypeEnum / rangeRequiredDescription
--secret-filetext—noCommand-specific option; see the full command details below.
--headerstext—yesCommand-specific option; see the full command details below.
--bodytext—yesCommand-specific option; see the full command details below.
--tolerance-secondsinteger1 to 86400noCommand-specific option; see the full command details below.
--atinteger0 to 4102444800noCommand-specific option; see the full command details below.
--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.

Shared server-guard guidance.

Consent

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

Retry

local: Local command; no HTTP retry.

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

Verify a webhook locally using the exact raw body and a JSON headers file. Use --secret-file or AKEDLY_WEBHOOK_SECRET (file wins). Tolerance defaults to 300 seconds inclusive; --at supplies Unix seconds for historical verification. Prints no body or secret.

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 webhooks verify workflow

Verify locally that a received Akedly webhook’s exact raw body matches its Svix signature and timestamp.

sh
akedly webhooks verify --secret-file ./private/webhook-secret.txt --headers ./fixtures/headers.json --body ./fixtures/body.json --at 1890000000

Input file: ./fixtures/headers.json (json).

json
{
  "svix-id": "msg_fixture_001",
  "svix-timestamp": "1890000000",
  "svix-signature": "v1,DAQq9ohld8V3MrFI74qZ+kK69edzQRDy7XNEl02DaPY="
}

Input file: ./fixtures/body.json (text).

text
{"event":"otp.verified","data":{"transactionID":"tx_example_001"}}

Input file: ./private/webhook-secret.txt (text).

text
[REDACTED — use your privately saved secret file]

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "valid": true,
    "timestampAgeSeconds": 0
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

The signing key and signature are synthetic and provided only to make this offline verification fixture internally consistent; never use this key in a deployed receiver.

Additional command forms

sh
akedly webhooks verify --secret-file <path> --headers <headers.json> --body <body-file>

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

This is a local computation: no API request is made. The exact raw body bytes are signed; re-serializing JSON changes the signature.

Common error guidance.