Skip to content
Akedly
Command reference

API keys

Akedly CLI command reference: API keys.

Build with AI agents

api-keys list

Review key labels, prefixes, scope and status without revealing one-time secrets.

When to use

  • Use before editing, rotating or revoking a key.

How it works

  1. Reads the account’s API-key inventory.

Expected outcome

A list of key metadata is returned.

Next steps

  • Use create for a new credential; never use a displayed prefix as a secret.

Usage

sh
akedly api-keys list

Inspect this command offline before preparing an operation:

sh
akedly describe "api-keys 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: api_keys:read.

Server request: GET /api-keys.

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 API keys.

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 workflow

Review key labels, prefixes, scope and status without revealing one-time secrets.

sh
akedly api-keys list

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": [
    {
      "id": "507f1f77bcf86cd799439014",
      "label": "Synthetic integration",
      "prefix": "aaaaaaaa",
      "replacesApiKeyId": null,
      "replacementRecoveryAvailable": false,
      "origin": "customer",
      "status": "active",
      "secretViewState": "viewed",
      "scope": {
        "mode": "all",
        "pipelineIds": [],
        "targets": []
      },
      "scopeSummary": "All pipelines",
      "spendLimitEgp": null,
      "settledUsageEgp": 0,
      "pendingUsageEgp": 0,
      "budgetUpdatedAt": null,
      "createdAt": "2030-01-01T00:00:00Z",
      "updatedAt": "2030-01-01T00:00:00Z",
      "lastUsedAt": null,
      "revokeEffectiveAt": null,
      "revokedAt": null,
      "configVersion": 1
    }
  ],
  "meta": {
    "maxActiveKeys": 10,
    "scopeEnforcementMode": "enforce",
    "scopeEditingEnabled": true,
    "scopeTargets": {
      "pipelines": [],
      "totpPipelines": []
    },
    "budgetEnforcementMode": "enforce",
    "budgetEditingEnabled": true,
    "budgetConfigUnavailable": false
  }
}

Inventory omits secret material; response metadata is extensible.

Additional command forms

sh
akedly api-keys 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

Inventory omits secret material; response metadata is extensible.

scope is a serialized object with mode, pipelineIds and typed targets; it is not a string.

Common error guidance.

api-keys create

Issue a scoped credential for an integration, optionally saving its one-time secret to a protected local sink.

When to use

  • Use when an integration needs its own credential or a rotation needs overlap.

How it works

  1. Issues a key using a generated or supplied idempotency key; after transient ambiguity it retries with the same key and may recover the secret once. Secret is returned once or delivered to --secret-file/--save.

Expected outcome

New key metadata and a one-time secret delivery result are returned.

Next steps

  • Store the secret in the integration’s secret manager, then revoke an old key only after deployment.

Usage

sh
akedly api-keys create

Inspect this command offline before preparing an operation:

sh
akedly describe "api-keys create" --output json

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--labeltext—Command-specific option; see the full command details below. Manifest body field: label.
--scopeenumall | selectedCommand-specific option; see the full command details below. Manifest body field: scope.mode, scope.pipelineIds, scope.targets.
--pipeline-idsids—Command-specific option; see the full command details below. Manifest body field: scope.mode, scope.pipelineIds, scope.targets.
--totp-pipeline-idsids—Command-specific option; see the full command details below. Manifest body field: scope.mode, scope.pipelineIds, scope.targets.
--spend-limit-egptext—Command-specific option; see the full command details below. Manifest body field: spendLimitEgp.
--idempotency-keytext—Command-specific option; see the full command details below. Manifest body field: idempotencyKey.
--replaces-api-key-idid—Command-specific option; see the full command details below. Manifest body field: replacesApiKeyId.
--saveboolean switch—Save the API key locally for Sending Commands and omit the Secret from output.
--secret-filetext—Write the secret to a new mode 0600 file and omit it from output; an existing path is refused.
--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: api_keys:create.

Server request: POST /api-keys.

Shared server-guard guidance.

Consent

--yes unless --scope selected is given, and always with --replaces-api-key-id or --save. --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, --save.

Full command details

Issue an API key. --replaces-api-key-id replaces an existing key and its old Secret stops immediately. To rotate without downtime, create a new key, deploy its Secret, then run akedly api-keys revoke <id> --grace-minutes <n> --yes. api-keys create repeats its own issue automatically: after a network error or HTTP 5xx it re-sends once with the same idempotency key, and if the response carries no Secret it calls recover-secret once; if that still fails, follow the error hint to recover by hand. Without --save or --secret-file the Secret is printed once in the output; use --secret-file or --save when output is logged or read by an agent. Creating a key that can use every pipeline (the default scope all) needs --yes, and so does --save, which makes the new key this region's saved default for Sending Commands; a --scope selected key without --save does not.

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 workflow

Issue a scoped credential for an integration, optionally saving its one-time secret to a protected local sink.

sh
akedly api-keys create --label 'Synthetic integration' --idempotency-key synthetic-idempotency-0001 --save --yes

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "id": "507f1f77bcf86cd799439014",
    "label": "Synthetic integration",
    "prefix": "aaaaaaaa",
    "replacesApiKeyId": null,
    "replacementRecoveryAvailable": false,
    "origin": "customer",
    "status": "active",
    "secretViewState": "viewed",
    "scope": {
      "mode": "all",
      "pipelineIds": [],
      "targets": []
    },
    "scopeSummary": "All pipelines",
    "spendLimitEgp": null,
    "settledUsageEgp": 0,
    "pendingUsageEgp": 0,
    "budgetUpdatedAt": null,
    "createdAt": "2030-01-01T00:00:00Z",
    "updatedAt": "2030-01-01T00:00:00Z",
    "lastUsedAt": null,
    "revokeEffectiveAt": null,
    "revokedAt": null,
    "configVersion": 1,
    "secretOperation": {
      "operation": "issue",
      "apiKeyId": "507f1f77bcf86cd799439014",
      "configVersion": 1,
      "requestKey": "synthetic-idempotency-0001"
    },
    "saved": {
      "region": "egypt",
      "prefix": "aaaaaaaa",
      "storage": "file",
      "default": true
    }
  }
}

Fake secret marker is synthetic and not usable. Prefer --secret-file or --save if command output may be logged. Idempotency key is generated if omitted.

A synthetic 64-character hexadecimal secret is omitted from output because --save is present; it is not a real credential.

Additional command forms

sh
akedly api-keys create --label terminal --yes
sh
akedly api-keys create --label terminal --save --yes
sh
akedly api-keys create --label ci --scope selected --pipeline-ids <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

Fake secret marker is synthetic and not usable. Prefer --secret-file or --save if command output may be logged. Idempotency key is generated if omitted.

Without --save or --secret-file, stdout includes the actual 64-character hexadecimal secret. With either sink, secret is omitted and saved/secretFile metadata is returned.

With --save, secret is removed from stdout and data.saved is {region,prefix,storage,default}. Without --save or --secret-file, the actual 64-hex secret is present in stdout. Use a private sink when output can be logged.

scope is a serialized object with mode, pipelineIds and typed targets; it is not a string.

Common error guidance.

api-keys update

Change an existing key’s label, allowed pipeline scope or spending cap.

When to use

  • Use to narrow a key after integration scope changes or adjust an authorized cap.

How it works

  1. Reads current config version when needed, then applies a version-checked patch; budget reduction requires explicit confirmation.

Expected outcome

Updated key settings are returned; the secret does not change.

Next steps

  • List the key to confirm configuration.

Usage

sh
akedly api-keys update <id>

Inspect this command offline before preparing an operation:

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

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--labeltext—Command-specific option; see the full command details below. Manifest body field: label.
--scopeenumall | selectedCommand-specific option; see the full command details below. Manifest body field: scope.mode, scope.pipelineIds, scope.targets.
--pipeline-idsids—Command-specific option; see the full command details below. Manifest body field: scope.mode, scope.pipelineIds, scope.targets.
--totp-pipeline-idsids—Command-specific option; see the full command details below. Manifest body field: scope.mode, scope.pipelineIds, scope.targets.
--spend-limit-egptext—Command-specific option; see the full command details below. Manifest body field: spendLimitEgp.
--confirm-budget-reductionboolean switch—Command-specific option; see the full command details below. Manifest body field: confirmBudgetReduction, expectedBudgetUpdatedAt.
--expected-config-versioninteger1 to unboundedCommand-specific option; see the full command details below. Manifest body field: expectedConfigVersion.
--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: api_keys:update.

Server request: PATCH /api-keys/:apiKeyId.

Shared server-guard guidance.

Consent

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

Retry

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

Output

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

Full command details

Edit API-key settings.

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 workflow

Change an existing key’s label, allowed pipeline scope or spending cap.

sh
akedly api-keys update 507f1f77bcf86cd799439013 --label 'Synthetic updated'

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "id": "507f1f77bcf86cd799439014",
    "label": "Synthetic updated",
    "prefix": "aaaaaaaa",
    "replacesApiKeyId": null,
    "replacementRecoveryAvailable": false,
    "origin": "customer",
    "status": "active",
    "secretViewState": "viewed",
    "scope": {
      "mode": "all",
      "pipelineIds": [],
      "targets": []
    },
    "scopeSummary": "All pipelines",
    "spendLimitEgp": null,
    "settledUsageEgp": 0,
    "pendingUsageEgp": 0,
    "budgetUpdatedAt": null,
    "createdAt": "2030-01-01T00:00:00Z",
    "updatedAt": "2030-01-01T00:00:00Z",
    "lastUsedAt": null,
    "revokeEffectiveAt": null,
    "revokedAt": null,
    "configVersion": 2
  }
}

Version conflicts require listing current keys and retrying against the current version.

Additional command forms

sh
akedly api-keys update 0123456789abcdef01234567 --label Renamed

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

Version conflicts require listing current keys and retrying against the current version.

scope is a serialized object with mode, pipelineIds and typed targets; it is not a string.

Common error guidance.

api-keys revoke

Stop an API key from authenticating, optionally allowing a chosen grace period for cutover.

When to use

  • Use after a replacement secret is deployed or immediately during compromise response.

How it works

  1. Requires explicit grace minutes and --yes; sends revocation request.

Expected outcome

Revocation state and effective grace metadata are returned.

Next steps

  • Verify the integration has moved to a replacement key.

Usage

sh
akedly api-keys revoke <id>

Inspect this command offline before preparing an operation:

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

Flags

FlagTypeEnum / rangeRequiredDescription
--ksaboolean switch—noSelect the KSA deployment.
--grace-minutesinteger0 to 1440yesCommand-specific option; see the full command details below. Manifest body field: graceMinutes.
--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: api_keys:delete.

Server request: POST /api-keys/:apiKeyId/revoke.

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

Revoke an API key with an explicit grace period.

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 workflow

Stop an API key from authenticating, optionally allowing a chosen grace period for cutover.

sh
akedly api-keys revoke 507f1f77bcf86cd799439013 --grace-minutes 0 --yes

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "id": "507f1f77bcf86cd799439014",
    "label": "Synthetic integration",
    "prefix": "aaaaaaaa",
    "replacesApiKeyId": null,
    "replacementRecoveryAvailable": false,
    "origin": "customer",
    "status": "revoked",
    "secretViewState": "viewed",
    "scope": {
      "mode": "all",
      "pipelineIds": [],
      "targets": []
    },
    "scopeSummary": "All pipelines",
    "spendLimitEgp": null,
    "settledUsageEgp": 0,
    "pendingUsageEgp": 0,
    "budgetUpdatedAt": null,
    "createdAt": "2030-01-01T00:00:00Z",
    "updatedAt": "2030-01-01T00:00:00Z",
    "lastUsedAt": null,
    "revokeEffectiveAt": null,
    "revokedAt": "2030-01-01T00:00:00Z",
    "configVersion": 1,
    "revokeOutcome": "updated"
  }
}

Irreversible credential effect; retries after ambiguity should be preceded by listing keys.

Additional command forms

sh
akedly api-keys revoke <id> --grace-minutes 0 --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

Irreversible credential effect; retries after ambiguity should be preceded by listing keys.

scope is a serialized object with mode, pipelineIds and typed targets; it is not a string.

Common error guidance.

api-keys recover-secret

Recover the one-time secret for a recently issued key whose initial delivery was interrupted.

When to use

  • Use the exact idempotency key or key id from the issuance result/error.

How it works

  1. Calls the recovery endpoint once and sends the returned secret to the selected output sink.

Expected outcome

The one-time secret is returned or saved.

Next steps

  • If recovery is unavailable, revoke the key and issue a replacement.

Usage

sh
akedly api-keys recover-secret

Inspect this command offline before preparing an operation:

sh
akedly describe "api-keys recover-secret" --output json

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--idempotency-keytext—Command-specific option; see the full command details below. Manifest body field: idempotencyKey.
--api-key-idid—Command-specific option; see the full command details below. Manifest body field: apiKeyId.
--saveboolean switch—Save the API key locally for Sending Commands and omit the Secret from output.
--secret-filetext—Write the secret to a new mode 0600 file and omit it from output; an existing path is refused.
--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: api_keys:create.

Server request: POST /api-keys/recover-secret.

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, --save.

Full command details

Recover a one-time API-key Secret.

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 workflow

Recover the one-time secret for a recently issued key whose initial delivery was interrupted.

sh
akedly api-keys recover-secret --idempotency-key synthetic-idempotency-0001 --save

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "id": "507f1f77bcf86cd799439014",
    "label": "Synthetic integration",
    "prefix": "aaaaaaaa",
    "replacesApiKeyId": null,
    "replacementRecoveryAvailable": false,
    "origin": "customer",
    "status": "active",
    "secretViewState": "viewed",
    "scope": {
      "mode": "all",
      "pipelineIds": [],
      "targets": []
    },
    "scopeSummary": "All pipelines",
    "spendLimitEgp": null,
    "settledUsageEgp": 0,
    "pendingUsageEgp": 0,
    "budgetUpdatedAt": null,
    "createdAt": "2030-01-01T00:00:00Z",
    "updatedAt": "2030-01-01T00:00:00Z",
    "lastUsedAt": null,
    "revokeEffectiveAt": null,
    "revokedAt": null,
    "configVersion": 1,
    "secretOperation": {
      "operation": "recover",
      "apiKeyId": "507f1f77bcf86cd799439014",
      "configVersion": 1,
      "requestKey": "synthetic-idempotency-0001"
    },
    "saved": {
      "region": "egypt",
      "prefix": "aaaaaaaa",
      "storage": "file",
      "default": true
    }
  }
}

Never place an actual secret in a human guide or transcript; synthetic marker shown.

A synthetic 64-character hexadecimal secret is omitted from output because --save is present; it is not a real credential.

Additional command forms

sh
akedly api-keys recover-secret --idempotency-key cli-example-idem-0001

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

Never place an actual secret in a human guide or transcript; synthetic marker shown.

Without --save or --secret-file, stdout includes the actual 64-character hexadecimal secret. With either sink, secret is omitted and saved/secretFile metadata is returned.

With --save, secret is removed from stdout and data.saved is {region,prefix,storage,default}. Without --save or --secret-file, the actual 64-hex secret is present in stdout. Use a private sink when output can be logged.

scope is a serialized object with mode, pipelineIds and typed targets; it is not a string.

Common error guidance.

api-keys claim

Claim the one-time secret for a key that exists but has not yet been viewed.

When to use

  • Use only to first-view an unseen migrated or signup-created key eligible for transition viewing.

How it works

  1. Posts claim for a key id and delivers the returned one-time secret to requested sink.

Prerequisites

  • Backend origin must be legacy-migrated or signup-dual; ordinary newly issued keys are not claimable.

Expected outcome

The secret is shown once or saved locally.

Next steps

  • Copy it into the integration’s secure secret store immediately.

Usage

sh
akedly api-keys claim <id>

Inspect this command offline before preparing an operation:

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

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--saveboolean switch—Save the API key locally for Sending Commands and omit the Secret from output.
--secret-filetext—Write the secret to a new mode 0600 file and omit it from output; an existing path is refused.
--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: api_keys:execute.

Server request: POST /api-keys/:apiKeyId/transition-view.

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, --save.

Full command details

Claim an unseen API-key Secret.

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 workflow

Claim the one-time secret for a key that exists but has not yet been viewed.

sh
akedly api-keys claim 507f1f77bcf86cd799439014 --save

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "id": "507f1f77bcf86cd799439014",
    "label": "Synthetic integration",
    "prefix": "aaaaaaaa",
    "replacesApiKeyId": null,
    "replacementRecoveryAvailable": false,
    "origin": "customer",
    "status": "active",
    "secretViewState": "viewed",
    "scope": {
      "mode": "all",
      "pipelineIds": [],
      "targets": []
    },
    "scopeSummary": "All pipelines",
    "spendLimitEgp": null,
    "settledUsageEgp": 0,
    "pendingUsageEgp": 0,
    "budgetUpdatedAt": null,
    "createdAt": "2030-01-01T00:00:00Z",
    "updatedAt": "2030-01-01T00:00:00Z",
    "lastUsedAt": null,
    "revokeEffectiveAt": null,
    "revokedAt": null,
    "configVersion": 1,
    "secretOperation": {
      "operation": "claim",
      "apiKeyId": "507f1f77bcf86cd799439014",
      "configVersion": 1,
      "requestKey": null
    },
    "saved": {
      "region": "egypt",
      "prefix": "aaaaaaaa",
      "storage": "file",
      "default": true
    }
  }
}

Synthetic secret marker is not a valid credential.

A synthetic 64-character hexadecimal secret is omitted from output because --save is present; it is not a real credential.

This is an eligible unseen legacy-migrated key synthetic example; ordinary newly issued keys cannot be claimed.

Additional command forms

sh
akedly api-keys claim <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

Synthetic secret marker is not a valid credential.

Without --save or --secret-file, stdout includes the actual 64-character hexadecimal secret. With either sink, secret is omitted and saved/secretFile metadata is returned.

With --save, secret is removed from stdout and data.saved is {region,prefix,storage,default}. Without --save or --secret-file, the actual 64-hex secret is present in stdout. Use a private sink when output can be logged.

scope is a serialized object with mode, pipelineIds and typed targets; it is not a string.

Common error guidance.

api-keys use

Select a previously saved API key as the default key for sending commands, or import one from a local secret file.

When to use

  • Use when multiple saved keys exist or a key was provisioned outside this CLI.

How it works

  1. Validates a secret file against its eight-character prefix when provided; otherwise finds an already saved key. Updates only local API-key selection.

Prerequisites

  • Without --secret-file, this prefix must already identify a saved key for the selected region. With --secret-file, its 64-hex secret must match the prefix.

Expected outcome

The selected prefix and local save metadata are returned.

Next steps

  • Run an API command that uses API-key auth to use the selected key.

Usage

sh
akedly api-keys use <prefix>

Inspect this command offline before preparing an operation:

sh
akedly describe "api-keys use" --output json
PositionalGrammarUsage guidance
<prefix>^[a-fA-F0-9]{8}$Required positional argument.

Flags

FlagTypeEnum / rangeDescription
--secret-filetext—Command-specific option; see the full command details below.
--ksaboolean switch—Select the KSA deployment.
--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: 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

Select or import a saved API key.

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 workflow

Select a previously saved API key as the default key for sending commands, or import one from a local secret file.

sh
akedly api-keys use aaaaaaaa

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "region": "egypt",
    "prefix": "aaaaaaaa",
    "default": true
  }
}

No network request occurs; a secret-file input is sensitive and must remain local.

Import a synthetic API key from a local file and select it as default

Import a separately provisioned key into the local store without sending it to Akedly, then make its prefix the default for API-key-authenticated commands.

sh
akedly api-keys use a1b2c3d4 --secret-file ./synthetic-api-key.secret

Input file: synthetic-api-key.secret (text).

text
[REDACTED — use your privately saved secret file]

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "region": "egypt",
    "prefix": "a1b2c3d4",
    "storage": "file",
    "default": true
  }
}

This is a synthetic, unissued key-shaped fixture; it is not a credential. The local reader accepts a 64-character hexadecimal secret and requires its first eight characters to match the positional prefix.

The command reads and stores this value locally and makes no network request. `storage` may be `keychain` when an OS keychain is available; `file` is the synthetic fallback result shown here.

The fixture contains fake secret material. Do not render its contents in a human guide or publish it as an example key.

Additional command forms

sh
akedly api-keys use <prefix>

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

No network request occurs; a secret-file input is sensitive and must remain local.

Common error guidance.