--- title: service-accounts description: Manage service accounts and issue keys safely. canonical_url: https://orchestor.io/docs/en/cli/service-accounts markdown_url: https://orchestor.io/docs/en/cli/service-accounts.md contentType: reference --- # service-accounts `orc service-accounts` creates machine-authentication principals bound to a Workspace, inspects and updates their roles and status, and issues API keys. Suspending an account disables its existing keys; you can activate it again later. The CLI manages only Workspace-bound service accounts. Creating, updating, and issuing keys requires `project:update` permission. Before issuing a key, prepare a new output file outside source control. ## Usage ```bash title="terminal" orc service-accounts list --workspace WORKSPACE_ID --json ``` *List service accounts.* ## Subcommands ### `list` Lists IDs, roles, status, and Workspace IDs. Use `--limit` and `--cursor` for pagination. ```bash title="terminal" orc service-accounts list [options] ``` ### `create` Creates a Workspace-scoped service account with a name. The CLI supports only `--scope workspace` and rejects `--scope organization`. ```bash title="terminal" orc service-accounts 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 service-accounts create --idempotency-key ``` ##### `--name` (required) Display name for the service account. Type: `string`. Optional. ```bash title="terminal" orc service-accounts create --name ``` ##### `--scope` Credential binding scope. Organization scope creates a service account without a Workspace binding.; enum: workspace|organization Type: `string`. Optional. ```bash title="terminal" orc service-accounts create --scope ``` ##### `--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 service-accounts create --workspace-id ``` ### `get` Retrieves current information for a service account ID. Run it with the target Workspace selected. ```bash title="terminal" orc service-accounts get [options] ``` ### `update` Updates the name or status. `status` is `active`, `suspended`, or `deleted`. `suspended` disables existing keys until the account returns to `active`. `deleted` is permanent. ```bash title="terminal" orc service-accounts update [options] ``` #### Unique options ##### `--name` Updated display name. Type: `string`. Optional. ```bash title="terminal" orc service-accounts update --name ``` ##### `--status` `active` — normal operation. `suspended` — all keys disabled, can be reactivated. `deleted` — permanent removal, all keys revoked.; enum: active|suspended|deleted Type: `string`. Optional. ```bash title="terminal" orc service-accounts update --status ``` ### `keys create` Issues a key using the service account ID, key name, permissions, and a new `--output` destination. The key is returned once and saved to an owner-only file. Existing files are not overwritten. ```bash title="terminal" orc service-accounts 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 service-accounts keys create --idempotency-key ``` ##### `--name` (required) Required display name for the key. Type: `string`. Optional. ```bash title="terminal" orc service-accounts keys create --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 service-accounts keys create --permissions ``` ## Examples ### Create a Workspace service account. ```bash title="terminal" orc service-accounts create --workspace WORKSPACE_ID --name "CI bot" --scope workspace --json ``` *Create a Workspace service account.* ### Suspend a service account. ```bash title="terminal" orc service-accounts update SERVICE_ACCOUNT_ID --workspace WORKSPACE_ID --status suspended --json ``` *Suspend a service account.* ### Save a read key to a private file. ```bash title="terminal" orc service-accounts keys create SERVICE_ACCOUNT_ID --workspace WORKSPACE_ID --name "CI read key" --permissions '{"answers":"read"}' --output /secure/path/service-account-key --json ``` *Save a read key to a private file.* ### Revoke an unused key. ```bash title="terminal" orc api-keys delete API_KEY_ID --workspace WORKSPACE_ID --yes --json ``` *Revoke an unused key.* ## Managing issued keys The CLI does not print the key to standard output or standard error. Do not paste the secret into logs, chat, Issues, or source code. Use the key ID in normal output and `service_account_id` in [`orc api-keys list`](https://orchestor.io/docs/cli/api-keys.md) to identify the key, then revoke unused keys with `orc api-keys delete`. ## Global Options The following [global options](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc service-accounts`: - [`--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)