Management APIs / Secrets

Create or update an organization secret

POSThttps://api.spice.ai/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.

Authorizations

  • AuthorizationstringRequired

    Bearer <token>. Authentication lists the tokens it accepts.

Path parameters

  • orgIdintegerRequired

    The org id from GET /v1/orgs

    • Minimum: 1

Header parameters

  • X-Org-Namestring

    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}$

Body

application/jsonRequired

  • namestringRequired

    • Maximum length: 255
    • Pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$

  • valuestringRequired

    • Maximum length: 10000

Responses

200The existing secret's value was replacedapplication/json

  • idinteger

    Unique identifier for the secret

  • namestring

    Name of the secret

  • valuestring

    Always masked with asterisks

  • created_atstring (date-time)

    Timestamp when the secret was created

  • updated_atstring (date-time)

    Timestamp when the secret was last updated

201The secret was createdapplication/json

  • idinteger

    Unique identifier for the secret

  • namestring

    Name of the secret

  • valuestring

    Always masked with asterisks

  • created_atstring (date-time)

    Timestamp when the secret was created

  • updated_atstring (date-time)

    Timestamp when the secret was last updated

400Bad 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

401Unauthorized

403Forbidden

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)

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

413Request body too large

500Internal server error

OpenAPIapi.spice.ai/openapi.json

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"
  }'
{
  "id": 0,
  "name": "string",
  "value": "string",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

application/json