# Create or update an organization secret

`POST /v1/orgs/{orgId}/secrets`

Creates an organization secret, or replaces the value of the one with the same name. The value is encrypted at rest and never returned. A name reserved by a platform-managed secret is refused.

## Path parameters

- `orgId` (integer, required): The org id from GET /v1/orgs. Minimum: `1`.

## Header parameters

- `Authorization` (string, required): `Bearer <token>`. [Authentication](https://spice.ai/docs/cloud/api/management#authentication) lists the tokens it accepts.
- `X-Org-Name` (string, optional): When present, X-Org-Name must name the same org as orgId. Otherwise the request returns org\_path\_mismatch (400). Pattern: `^[A-Za-z0-9._-]{1,255}$`.

## Request body

Required.

Content type: `application/json`

- `name` (string, required): Maximum length: `255`. Pattern: `^[a-zA-Z_][a-zA-Z0-9_]*$`.
- `value` (string, required): Maximum length: `10000`.

## Example request

```bash
curl -X POST "https://api.spice.ai/v1/orgs/<orgId>/secrets" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "value": "string"
  }'
```

```http
POST /v1/orgs/<orgId>/secrets HTTP/1.1
Host: api.spice.ai
Authorization: Bearer <token>
Content-Type: application/json
Content-Length: 43

{
  "name": "string",
  "value": "string"
}
```

## Responses

**200 OK**

The existing secret's value was replaced

Content type: `application/json`

- `id` (integer): Unique identifier for the secret
- `name` (string): Name of the secret
- `value` (string): Always masked with asterisks
- `created_at` (string (date-time)): Timestamp when the secret was created
- `updated_at` (string (date-time)): Timestamp when the secret was last updated

**201 Created**

The secret was created

Content type: `application/json`

- `id` (integer): Unique identifier for the secret
- `name` (string): Name of the secret
- `value` (string): Always masked with asterisks
- `created_at` (string (date-time)): Timestamp when the secret was created
- `updated_at` (string (date-time)): Timestamp when the secret was last updated

**400 Bad Request**

Invalid org id (`invalid_org_id`), X-Org-Name does not name that org (`org_path_mismatch`), or the JSON body is not valid

**401 Unauthorized**

Unauthorized

**403 Forbidden**

Insufficient scope (requires secrets:write), the viewer role, or the caller is not a member of the organization (`org_forbidden`), a machine credential named an organization other than its own (`org_assertion_mismatch`), or the organization a machine credential is bound to has been deleted (`org_deleted`)

**409 Conflict**

The name is reserved by a platform-managed secret (code: `secret_name_reserved`)

**413 Content Too Large**

Request body too large

**500 Internal Server Error**

Internal server error

OpenAPI: [api.spice.ai/openapi.json](https://api.spice.ai/openapi.json)