---
title: Make your first request with an API key
description: Make your first request with an API key.
canonical_url: https://orchestor.io/docs/en/cli/workflows/api-key-setup
markdown_url: https://orchestor.io/docs/en/cli/workflows/api-key-setup.md
contentType: how-to
---

# Make your first request with an API key

Use CLI authentication to create a workspace API key and save its one-time secret to a safe file. An API key cannot manage other keys.

## Steps

```bash
orc auth login
orc api-keys create \
  --workspace WORKSPACE_ID \
  --name "Read automation" \
  --type read_only \
  --scope workspace \
  --output /secure/path/api-key \
  --json
```

Pass a path that does not exist to `--output`. The CLI atomically writes the secret to an owner-only (`0600`) file and never overwrites an existing file. The JSON on stdout contains non-secret metadata only. The CLI creates `workspace`-scoped keys only.

## Use the key

Inject the key into the process environment from the protected file, then verify the required read. Do not print its value.

```bash
export ORCHESTOR_API_KEY="$(< /secure/path/api-key)"
orc brands list --workspace WORKSPACE_ID --json
```

## List, update, and replace keys

```bash
orc api-keys list --workspace WORKSPACE_ID --json
orc api-keys update KEY_ID --workspace WORKSPACE_ID --name "Read automation v2" --json
```

To replace a key, create the replacement at a different new path. Verify the required read with the new key before revoking the old key.

```bash
orc api-keys create \
  --workspace WORKSPACE_ID \
  --name "Read automation replacement" \
  --type read_only \
  --output /secure/path/api-key-next \
  --json
orc api-keys delete OLD_KEY_ID --workspace WORKSPACE_ID --yes --json
```

[api-keys reference](https://orchestor.io/docs/en/cli/api-keys.md) · [Workflow index](https://orchestor.io/docs/en/cli/workflows.md)

If a failure remains, [report it and verify the fix](https://orchestor.io/docs/cli/workflows/workflow-feedback.md), including this workflow and the failed step.

---

[Documentation index](https://orchestor.io/docs/llms.txt)