Secrets management

AI Workspace lets you store sensitive credentials as secrets and reference them securely in artifact configurations. Secrets are encrypted at rest using AES-GCM-256. Plaintext values are never written to the database and are never returned in any API response—not even the creation response.

Use secrets to keep raw API keys, tokens, and passwords out of your artifact configurations. They apply to the following:

• Large language model (LLM) provider configurations
• Model Context Protocol (MCP) proxy configurations
• API backend settings

Not the same as config.toml interpolation

Secrets apply to artifact configurations only, and the gateway resolves the {{ secret "handle" }} placeholder at request time. The services have their own startup credentials: the database password, the OpenID Connect (OIDC) client secret, and the at-rest encryption key. Those are supplied through the separate {{ env }} and {{ file }} tokens in config.toml. See Sensitive values in config.toml. The two placeholder sets aren't interchangeable.

How it works

1. Create a secret via the Platform API with a unique handle and the plaintext value.
2. Reference the secret in any artifact configuration using the placeholder syntax:

{{ secret "your-secret-handle" }}

1. When an artifact that contains a placeholder is deployed, the gateway resolves it with the decrypted value at runtime — the plaintext never appears in the control-plane database or configuration files.
2. To rotate a credential, call PUT /api/v0.9/secrets/{secretId} with the new value. Because artifacts reference the secret by handle, no artifact changes or redeployment are required.

Automatic encryption in the AI Workspace UI

When you create or update an LLM Provider or MCP Proxy through the AI Workspace UI and fill in an upstream API key or auth value, the UI automatically:

1. Creates a secret via POST /api/v0.9/secrets using a deterministic handle derived from the resource ID (for example, wso2-openai-provider-api-key).
2. Substitutes the credential with the {{ secret "handle" }} placeholder before saving the resource.

The raw credential is sent to the secrets API only once and is never stored in the artifact configuration. Re-saving a resource that already contains a placeholder skips the secret creation step.

API reference

The secrets API is available at /api/v0.9/secrets. All requests require a valid JSON Web Token (JWT) with the appropriate scope.

Required scopes

Scope	Grants
ap:secret:read	List secrets and get metadata by handle
ap:secret:create	Create a new secret
ap:secret:update	Rotate or update a stored secret value
ap:secret:delete	Delete a secret
ap:secret:manage	All of the above

Create a secret

POST /api/v0.9/secrets
Content-Type: multipart/form-data

Stores a new encrypted secret. The plaintext value is never returned — not even in this response.

Why multipart/form-data?

multipart/form-data carries the value field as arbitrary content, so the same endpoint accepts text and binary secrets under one content type.

Request fields

Field	Required	Description
displayName	Yes	Human-readable display name for the secret.
value	Yes	The sensitive value to encrypt and store.
id	No	Handle (slug) that identifies the secret within the organization. Used in {{ secret "id" }} references. Generated from displayName when omitted, and immutable after creation.
description	No	Optional description.
type	No	Secret type, either GENERIC (default) for API keys and tokens, or CERTIFICATE.

Example request

POST /api/v0.9/secrets
Authorization: Bearer <JWT>
Content-Type: multipart/form-data; boundary=----FormBoundary

------FormBoundary
Content-Disposition: form-data; name="id"

wso2-openai-key
------FormBoundary
Content-Disposition: form-data; name="displayName"

WSO2 OpenAI API Key
------FormBoundary
Content-Disposition: form-data; name="description"

API key for WSO2 OpenAI integration
------FormBoundary
Content-Disposition: form-data; name="type"

GENERIC
------FormBoundary
Content-Disposition: form-data; name="value"

sk-xxx
------FormBoundary--

Response — 201 Created

{
  "id": "wso2-openai-key",
  "displayName": "WSO2 OpenAI API Key",
  "createdBy": "john.doe",
  "updatedBy": "john.doe",
  "createdAt": "2026-01-12T10:00:00Z",
  "updatedAt": "2026-01-12T10:00:00Z"
}

The response doesn't include the value. Store the plaintext in a secure location before submitting it—you can't retrieve it later.

Error responses

Status	Reason
400	Missing required fields or invalid request
409	A secret with the same id already exists in the organization

List secrets

GET /api/v0.9/secrets

Returns metadata for all secrets in the organization. Plaintext values are never included.

Query parameters

Parameter	Default	Max	Description
limit	20	100	Maximum number of results to return
offset	0	—	Number of results to skip for pagination
updatedAfter	—	—	RFC 3339 timestamp. Returns only secrets updated after this time.

Response — 200 OK

{
  "count": 1,
  "list": [
    {
      "id": "wso2-openai-key",
      "displayName": "WSO2 OpenAI API Key",
      "description": "API key for WSO2 OpenAI integration",
      "type": "GENERIC",
      "provider": "IN_BUILT",
      "status": "ACTIVE",
      "hash": "hmac-sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe04294e576d4b3d4c57e3f428a",
      "createdBy": "john.doe",
      "createdAt": "2026-01-12T10:00:00Z",
      "updatedAt": "2026-01-12T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

Get secret metadata

GET /api/v0.9/secrets/{secretId}

Returns metadata for a single secret. The plaintext value isn't included.

Response — 200 OK

{
  "id": "wso2-openai-key",
  "displayName": "WSO2 OpenAI API Key",
  "description": "API key for WSO2 OpenAI integration",
  "type": "GENERIC",
  "provider": "IN_BUILT",
  "status": "ACTIVE",
  "hash": "hmac-sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe04294e576d4b3d4c57e3f428a",
  "createdBy": "john.doe",
  "createdAt": "2026-01-12T10:00:00Z",
  "updatedAt": "2026-01-12T10:00:00Z"
}

Error responses

Status	Reason
404	No secret found with the given handle in this organization

Rotate a secret

PUT /api/v0.9/secrets/{secretId}
Content-Type: multipart/form-data

Re-encrypts and stores a new value. Because id is immutable, all {{ secret "id" }} placeholders across existing resources remain valid without modification. The plaintext value isn't returned in the response.

Request fields

Field	Required	Description
displayName	Yes	Display name for the secret.
value	Yes	The new sensitive value to encrypt and store.
description	No	Updated description.
id	No	Secret handle. When supplied it must match the path parameter, otherwise the request fails with 400. The handle cannot be changed by an update.

Example request

PUT /api/v0.9/secrets/wso2-openai-key
Authorization: Bearer <JWT>
Content-Type: multipart/form-data; boundary=----FormBoundary

------FormBoundary
Content-Disposition: form-data; name="value"

sk-new-value
------FormBoundary
Content-Disposition: form-data; name="displayName"

WSO2 OpenAI API Key (rotated)
------FormBoundary
Content-Disposition: form-data; name="description"

Rotated on 2026-06-26 — old key decommissioned
------FormBoundary--

Response — 200 OK

{
  "id": "wso2-openai-key",
  "displayName": "WSO2 OpenAI API Key (rotated)",
  "createdBy": "john.doe",
  "updatedBy": "john.doe",
  "createdAt": "2026-01-12T10:00:00Z",
  "updatedAt": "2026-06-26T11:30:00Z"
}

Notes

• If the secret's status is DEPRECATED (previously soft-deleted), a successful rotation sets it back to ACTIVE. New resources can reference the secret again, and the gateway includes it in the next sync.
• The gateway picks up the updated value on its next sync cycle — no redeployment of referencing artifacts is required.

Error responses

Status	Reason
404	No secret found with the given handle

Delete a secret

DELETE /api/v0.9/secrets/{secretId}

Soft-deletes a secret by setting its status to DEPRECATED. Deletion is blocked with 409 Conflict if any artifact references the secret — either in its saved configuration or in a snapshot deployed to a gateway.

Response — 204 No Content

Error responses

Status	Reason
404	No secret found with the given handle
409	Secret is still referenced by one or more artifacts

409 response example

{
  "status": "error",
  "code": "SECRET_IN_USE",
  "message": "The secret is referenced by one or more active resources.",
  "details": {
    "references": [
      { "type": "llm_provider", "handle": "openai-provider", "name": "OpenAI Provider" },
      { "type": "mcp_proxy",    "handle": "my-mcp-proxy",    "name": "My MCP Proxy" }
    ]
  }
}

Every Platform API error uses this shape: a literal status of error, a stable machine-readable code, a human-readable message, and — depending on the condition — errors, details, or a trackingId. Branch on code, not on the HTTP status.

---

Reference a secret in an artifact configuration

Use the following placeholder syntax wherever a configuration field accepts a sensitive string value:

{{ secret "your-secret-handle" }}

Example — LLM provider upstream API key

spec:
  upstream:
    auth:
      type: api-key
      header: Authorization
      value: 'Bearer {{ secret "wso2-openai-key" }}'

Validation at save time

When creating or updating any resource that contains {{ secret "..." }} references, the Platform API validates that an active secret with the referenced handle exists in the organization. If any placeholder can't be resolved, the request is rejected with 400 Bad Request and the list of unresolvable handles.

Rotate a credential

To rotate a credential without touching artifact configurations:

1. Call PUT /api/v0.9/secrets/{secretId} with the new value.
2. The gateway picks up the updated secret on the next sync cycle.

No artifact changes or redeployment are required because resources reference the secret by handle, not by value.

Delete a secret safely

Deleting a secret that's still in use returns HTTP 409. To remove it cleanly:

1. Inspect the references list in the 409 response.
2. Update each referencing artifact to remove or replace the {{ secret "handle" }} reference.
3. Redeploy the updated artifacts to the gateway.
4. Retry DELETE /api/v0.9/secrets/{secretId}.

Encryption key

Secrets are encrypted at rest with the Platform API's at-rest encryption key, which also protects subscription tokens. The setup script provisions this key for Docker Compose deployments. For how to generate, mount, and reference it, see Provision the at-rest encryption key manually.

Warning

Use the same encryption key across restarts and across all replicas. Changing or rotating it makes previously-encrypted secrets unreadable.