> ## Documentation Index
> Fetch the complete documentation index at: https://docs.creao.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets

> Add, update, and list account secret keys through the Developer API. Values are never returned.

## Overview

Account secrets store API keys and other credentials for agent sandboxes. After you save a secret, agents can read it as `process.env.SECRET_NAME`. The Developer API can add a secret, update it, list keys, and delete it.

Values are write-only. List, create, and update responses return metadata only — never the secret value.

Secrets are account-scoped, not workspace-scoped. Every personal-agent run for the Account API key owner receives the same secrets.

## Add a secret

```bash theme={null}
curl -X POST https://developer.creao.ai/v1/secrets \
  -H "Authorization: Bearer cr_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "X_BEARER_TOKEN",
    "value": "your_token_here",
    "description": "X API bearer token"
  }'
```

```json theme={null}
{
  "id": "77777777-7777-4777-8777-777777777777",
  "name": "X_BEARER_TOKEN",
  "description": "X API bearer token",
  "created_at": "2026-08-16T00:00:00.000Z",
  "updated_at": "2026-08-16T00:00:00.000Z"
}
```

Name rules:

* Uppercase letters, digits, and underscores only
* Must start with a letter or underscore
* At most 255 characters
* At most 50 secrets per account
* Value at most 8 KB
* Some platform environment names are reserved (`PATH`, `OPENAI_API_KEY`, and similar)

## List secret keys

```bash theme={null}
curl https://developer.creao.ai/v1/secrets \
  -H "Authorization: Bearer cr_sk_your_key_here"
```

```json theme={null}
{
  "secrets": [
    {
      "id": "77777777-7777-4777-8777-777777777777",
      "name": "X_BEARER_TOKEN",
      "description": "X API bearer token",
      "created_at": "2026-08-16T00:00:00.000Z",
      "updated_at": "2026-08-16T00:00:00.000Z"
    }
  ]
}
```

This endpoint is not paginated. The listing never includes `value`.

## Update a secret

```bash theme={null}
curl -X PATCH https://developer.creao.ai/v1/secrets/X_BEARER_TOKEN \
  -H "Authorization: Bearer cr_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "rotated_token"
  }'
```

The path uses the secret **name**, not the id. The name cannot be changed. Send at least one of `value` or `description`.

## Delete a secret

```bash theme={null}
curl -X DELETE https://developer.creao.ai/v1/secrets/X_BEARER_TOKEN \
  -H "Authorization: Bearer cr_sk_your_key_here"
```

```json theme={null}
{
  "deleted": true
}
```

## Errors

| Code                   | When                                                           |
| ---------------------- | -------------------------------------------------------------- |
| `SECRET_NOT_FOUND`     | No secret with that name exists for this account               |
| `SECRET_CONFLICT`      | A secret with this name already exists                         |
| `SECRET_LIMIT_REACHED` | The account already has 50 secrets                             |
| `SECRET_NAME_RESERVED` | The name collides with a platform-managed environment variable |
| `SECRET_NAME_INVALID`  | The name is empty, too long, or not an env-var identifier      |
| `SECRET_VALIDATION`    | The value is empty or larger than 8 KB                         |
| `INVALID_INPUT`        | Missing required fields or unknown field                       |

See also the OpenAPI operations under [Secrets](/developer-api/secrets/list-secrets).