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

# Save a secret

> Save a secret to your account or to one workspace from code, including a client account’s workspace.

Saves a secret to your account, or to one workspace when you send `workspace_id`. Saving a name that already exists replaces its value. The value is encrypted, and no list or save call returns it.

This is the way to give a [client account](https://docs.orgo.ai/guides/invoicing.md)'s workspace a secret: that workspace is not in the picker in [Settings → Secrets](https://www.orgo.ai/settings/secrets).

Saving does not change a computer that already exists. To put a saved secret on computers, call [Apply secrets to many computers](https://docs.orgo.ai/api-reference/secrets/apply.md).

## Body parameters

**name** `string` *required*

Up to 64 letters, digits, `_` and `-`. Orgo saves it in capitals with `-` as `_`, so `anthropic-api-key` becomes `ANTHROPIC_API_KEY`.

**value** `string` *required*

The secret, up to 8,192 characters. It can't be empty.

**workspace\_id** `string`

A workspace UUID. The secret then belongs to that workspace, and it takes the place of an account secret of the same name there. Left out, or not a UUID, the secret belongs to your account.

## Example

```bash theme={null}
curl -X POST https://www.orgo.ai/api/secrets \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "ANTHROPIC_API_KEY", "value": "sk-ant-...", "workspace_id": "'"$WORKSPACE_ID"'"}'
```

Send an account-wide key. A restricted key needs Secrets write.

## Response

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

## Errors

| Status | Body | When |
| - | - | - |
| `400` | `{ "error": "invalid JSON" }` | The body is not JSON. |
| `400` | `{ "error": "Invalid name. Use letters, numbers, _ or - (max 64 chars)." }` | `name` is missing or not allowed. |
| `400` | `{ "error": "A value is required." }` | `value` is missing or empty. |
| `400` | `{ "error": "Value is too long." }` | `value` is over 8,192 characters. |
| `401` | `{ "error": "Not authenticated" }` | No key, or one that is not a known Orgo key. |
| `403` | `{ "error": "This endpoint requires an account-wide credential (workspace_scope_mismatch).", "code": "workspace_scope_mismatch" }` | The key is scoped to one workspace. |
| `404` | `{ "error": "Workspace not found" }` | You can't reach `workspace_id`. |
| `500` | `{ "error": "Server error" }` | The save failed. Retry. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.