--- title: api-keys description: Create, update, and revoke Workspace API keys. canonical_url: https://orchestor.io/docs/en/cli/api-keys markdown_url: https://orchestor.io/docs/en/cli/api-keys.md contentType: reference --- # api-keys `orc api-keys` creates API keys for the selected Workspace, inspects and updates metadata and permissions, and revokes unused keys. The one-time secret returned on creation is saved to a new private file; normal output contains only metadata. Use the CLI identity obtained with [`orc auth login`](https://orchestor.io/docs/cli/auth.md). Browser API session authentication is also supported, but an API key cannot manage keys. The CLI creates Workspace-scoped keys only. ## Usage ```bash title="terminal" orc api-keys list --json ``` *List API key metadata.* ## Subcommands ### `list` Lists key metadata. Use `--limit` and `--cursor` for pagination. The response contains no secrets. ```bash title="terminal" orc api-keys list [options] ``` ### `create` Creates a key using `--name` and a new destination in `--output`. `--mode` is `live` or `test`; `--type` is `read_only` or `read_write`. `--scope organization` and `workspace_id: null` are rejected before calling the API. ```bash title="terminal" orc api-keys create [options] ``` #### Unique options ##### `--idempotency-key` Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation. Type: `string`. Optional. ```bash title="terminal" orc api-keys create --idempotency-key ``` ##### `--mode` Key mode. `live` consumes credits, `test` uses sandbox.; enum: live|test Type: `string`. Optional. ```bash title="terminal" orc api-keys create --mode ``` ##### `--name` (required) Required human-readable name. Type: `string`. Optional. ```bash title="terminal" orc api-keys create --name ``` ##### `--scope` Credential binding scope. Organization scope creates a key without a Workspace binding.; enum: workspace|organization Type: `string`. Optional. ```bash title="terminal" orc api-keys create --scope ``` ##### `--type` Permission type. `read_only` grants read access; `read_write` grants read and write access.; enum: read_only|read_write Type: `string`. Optional. ```bash title="terminal" orc api-keys create --type ``` ##### `--workspace-id` Optional explicit Workspace binding. Omit for the current Workspace; use null with organization scope.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc api-keys create --workspace-id ``` ### `update` Updates `--name`, `--type`, or a JSON object in `--permissions` for the specified key ID. This does not retrieve the secret again. ```bash title="terminal" orc api-keys update [options] ``` #### Unique options ##### `--name` New display name. Type: `string`. Optional. ```bash title="terminal" orc api-keys update --name ``` ##### `--permissions` Endpoint-group permission map. Each key is an endpoint group name, value is the access level. Unspecified groups default to `none`.; (JSON object, e.g. '{"custom_id":"x"}') Type: `string`. Optional. ```bash title="terminal" orc api-keys update --permissions ``` ##### `--type` Permission preset for a user-owned key.; enum: read_only|read_write Type: `string`. Optional. ```bash title="terminal" orc api-keys update --type ``` ### `delete` Revokes the specified key ID. Revocation cannot be undone. Non-interactive execution requires `--yes`. ```bash title="terminal" orc api-keys delete [options] ``` ## Examples ### Create a key and save its secret to a new private file. ```bash title="terminal" orc api-keys create --workspace WORKSPACE_ID --name "Automation key" --scope workspace --output /secure/path/api-key --json ``` *Create a key and save its secret to a new private file.* ### Rename a key. ```bash title="terminal" orc api-keys update KEY_ID --workspace WORKSPACE_ID --name "Renamed key" --json ``` *Rename a key.* ### Revoke an unused key. ```bash title="terminal" orc api-keys delete KEY_ID --workspace WORKSPACE_ID --yes --json ``` *Revoke an unused key.* ## Saving the secret Pass a file that does not exist to `--output`. The CLI saves it atomically with owner-only permissions (`0600`) and does not overwrite existing files. Prepare the parent directory and choose a location outside source control. Standard output contains metadata with the secret removed. ## Global Options The following [global options](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc api-keys`: - [`--help`](https://orchestor.io/docs/cli/global-flags.md#help) - [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#workspace) - [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-output) - [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-output) - [`--format`](https://orchestor.io/docs/cli/global-flags.md#output-format) - [`--field`](https://orchestor.io/docs/cli/global-flags.md#field-selection) - [`--fields`](https://orchestor.io/docs/cli/global-flags.md#field-selection) - [`--raw`](https://orchestor.io/docs/cli/global-flags.md#raw-output) - [`--output`](https://orchestor.io/docs/cli/global-flags.md#file-output) - [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#pager) - [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#dry-run) - [`--yes`](https://orchestor.io/docs/cli/global-flags.md#confirmation) - [`--limit`](https://orchestor.io/docs/cli/global-flags.md) - [`--cursor`](https://orchestor.io/docs/cli/global-flags.md) - [`--stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input) - [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input) - [`--page-all`](https://orchestor.io/docs/cli/global-flags.md#all-pages) - [`--timing`](https://orchestor.io/docs/cli/global-flags.md#request-timing) - [`--readonly`](https://orchestor.io/docs/cli/global-flags.md#read-only-mode) - [`--wrap-untrusted`](https://orchestor.io/docs/cli/global-flags.md#untrusted-content-wrapping) For details and examples, see [global options](https://orchestor.io/docs/cli/global-flags.md). --- [Documentation index](https://orchestor.io/docs/llms.txt)