# Manage secrets (https://luxor.ai/docs/secrets/manage-secrets)

> For the complete documentation index, see [llms.txt](https://luxor.ai/llms.txt)

Create, inspect, rotate, and revoke workspace secrets.

Manage secrets from the dashboard or the `luxor secrets` CLI. Commands use the workspace selected during login.

## Access permissions

Your account needs workspace-edit permission. When creating an API key or approving a CLI login, select **Allow Secrets access**. If an existing key lacks access, create a replacement or log in again and select that option.

## Create a secret

Use an authenticated CLI from the [quickstart](https://luxor.ai/docs/sandbox/quickstart.md).

This example saves a GitHub personal access token. Use a token with only the permissions your application needs.

```bash
luxor secrets create GITHUB_TOKEN
```

Wait for `Secret value (hidden):`, paste your token, and press Enter. Paste only the token, without a `Bearer ` prefix. The prompt hides your input and keeps the value out of your shell command history.

Keep the secret ID printed by the command. The name is used in requests; the ID is used to manage the secret later.

For a complete configuration file or private key, read the value from a local file instead:

```bash
luxor secrets create SERVICE_CONFIG --file ./service-config.json
```

File input preserves the exact bytes, including trailing newlines. You can also use `--stdin` or `--from-env VARIABLE_NAME` for scripts.

With the `luxor` CLI **2.11.0 or later**, add `--description` to say what the secret is for. The description is one line of up to 256 characters, shown to the people who manage the secret:

```bash
luxor secrets create GITHUB_TOKEN --description "Read-only token for the build sandbox"
```

## Inspect a secret

In the dashboard, open your workspace's **Secrets** page. Secret values and [request policies](https://luxor.ai/docs/secrets/request-policies.md) are managed separately.

From the CLI, inspect metadata with:

```bash
luxor secrets list
luxor secrets get SECRET_ID
luxor secrets versions SECRET_ID
```

Replace `SECRET_ID` with the ID returned when you created the secret. Listing and inspecting a secret do not reveal its value.

With the `luxor` CLI **2.11.0 or later**, the list shows each secret's description and where it is available. To narrow it:

```bash
luxor secrets list --availability workspace
luxor secrets list --availability repository
luxor secrets list --repository your-org/your-repo
```

The dashboard's **Secrets** page has the same filters, a **Description** column, and an availability label on each secret.

## Rotate a value

A secret's **version** identifies a stored value. Its **revision** identifies the current state of its metadata and protects updates against concurrent changes.

Read the current revision with `secrets get`, then update the value. In a terminal, omit the input flags and the `luxor` CLI **2.11.0 or later** asks for the new value with a hidden prompt, so it stays out of your shell history:

```bash
luxor secrets update SECRET_ID --revision REVISION
```

The prompt refuses an empty entry. To set an empty value on purpose, use `--stdin`, `--file`, or `--from-env`. In a script, pass the value that way. This example reads a replacement token from a local file:

```bash
luxor secrets update SECRET_ID --revision REVISION --file ./replacement-token.txt
```

Replace `REVISION` with the number you just read. File input preserves the exact bytes, including a trailing newline, so ensure the file contains only the token. You can also use `--stdin` or `--from-env VARIABLE_NAME` for automation.

The new value becomes active. Subsequent injected requests use it immediately; guest environment variables and files need a new sandbox. Luxor Agent Cloud does not refresh or renew credentials with the provider for you.

To select an earlier, unrevoked version:

```bash
luxor secrets update SECRET_ID --revision REVISION --active-version VERSION
```

## Change a description or availability

A secret is available to the whole workspace by default, which means every CI job and sandbox in it can use the secret.
A repository secret is available only to CI jobs in one repository. Sandboxes and request policies use workspace secrets only.

Edit a secret's description or availability without changing its value (the `luxor` CLI **2.11.0 or later**):

```bash
luxor secrets update SECRET_ID --revision REVISION --description "Deploy token for staging"
luxor secrets update SECRET_ID --revision REVISION --repository your-org/your-repo
luxor secrets update SECRET_ID --revision REVISION --availability workspace
```

`--repository owner/name` moves a secret to that repository, which must be connected to the workspace (`luxor secrets repositories` lists them).
`--availability workspace` moves it back, and cannot be combined with `--repository`.
Pass an empty `--description ""` to clear the description.
These changes do not create a new version and do not restore a revoked secret. You can also make them from the secret's edit dialog on the **Secrets** page.

Two kinds of secret cannot move to a repository:

* A secret that a request policy uses. The error names the policies, for example `secret policies github use this secret`. Remove the secret from those policies first.
* A secret created for a storage connection with `--scope s3_storage`. These are available to storage connections only.

Creating a repository secret also takes `--repository owner/name`.
In the dashboard, replacing a secret's value no longer offers an undo or a revoke option; switch or revoke versions from **Versions** instead.

## Revoke or delete a secret

Use the current revision for either operation:

```bash
luxor secrets revoke SECRET_ID --revision REVISION
```

This revokes all current value versions and prevents further resolution of the secret. Revoked versions cannot be used again, but you can restore the secret by updating it with a new value. To revoke only one version, add `--version VERSION`.

To delete a secret you no longer need:

```bash
luxor secrets delete SECRET_ID --revision REVISION
```

Deleting or revoking a secret does not revoke the credential at its provider. Recreating a secret or policy with the same name does not silently reconnect existing policy or sandbox attachments to the new object.

## Use a saved secret

Follow [Using secrets in a sandbox](https://luxor.ai/docs/sandbox/secrets.md) for environment variables, files, and transparent injection. The guide also explains what happens during rotation, revocation, and pause/resume.