Skip to content

Secrets

Encrypted secret management — create, rotate, and delete organization-scoped secrets referenced via {{ secret "name" }} placeholders

Create a secret

POST /secrets

Code samples

curl -X POST https://localhost:9243/api/v0.9/secrets \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: multipart/form-data' \
  -H 'Accept: application/json' \
  -F 'id=wso2-openai-key' \
  -F 'displayName=WSO2 OpenAI API Key' \
  -F 'description=Primary API key for WSO2 OpenAI integration' \
  -F 'value=sk-xxx' \
  -F 'type=GENERIC'

Create a new encrypted secret scoped to the organization. The plaintext value is never returned.

Authentication

Parameters

Name In Type Required Description
body body SecretCreateRequest true none

Example responses

201 Response

{
  "id": "wso2-openai-key",
  "displayName": "WSO2 OpenAI API Key",
  "createdBy": "john.doe",
  "updatedBy": "john.doe",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

400 Response

{
  "status": "error",
  "code": "VALIDATION_FAILED",
  "message": "The request failed validation.",
  "errors": [
    {
      "field": "<name of the offending field>",
      "message": "<reason this field failed validation>"
    }
  ]
}

401 Response

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Authorization header is required, or the token is invalid or expired."
}

403 Response

{
  "status": "error",
  "code": "FORBIDDEN",
  "message": "You do not have permission to perform this action."
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "The request conflicts with the current state of the resource."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred.",
  "trackingId": "4f1c6f2e-8a4b-4c93-b1de-9f2f6f0c2a11"
}

503 Response

{
  "status": "error",
  "code": "SERVICE_UNAVAILABLE",
  "message": "Secrets management is not configured.",
  "trackingId": "4f1c6f2e-8a4b-4c93-b1de-9f2f6f0c2a11"
}

Responses

Status Meaning Description Schema
201 Created Secret created successfully. SecretResponse
400 Bad Request Bad Request. Invalid request or validation error. Error
401 Unauthorized Unauthorized. Authentication credentials are missing or invalid. Error
403 Forbidden Forbidden. The authenticated user does not have permission to access this resource. Error
409 Conflict Conflict. The request conflicts with the current state of the resource. Error
500 Internal Server Error Internal Server Error. Error
503 Service Unavailable Service Unavailable. The secrets management feature is not configured. Error

Response Headers

Status Header Type Format Description
201 Location string uri URL of the newly created resource.

List secrets

GET /secrets

Code samples

curl -X GET https://localhost:9243/api/v0.9/secrets \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Accept: application/json'

Returns metadata for all secrets in the organization. The plaintext value is never included in list or get responses.

Authentication

Parameters

Name In Type Required Description
limit query integer false Maximum number of items to return per page.
offset query integer false Zero-based index of the first item to return.
updatedAfter query string(date-time) false RFC3339 timestamp — return only secrets updated after this time. Used by GW controller for incremental polling.

Example responses

200 Response

{
  "count": 0,
  "list": [
    {
      "id": "wso2-openai-key",
      "displayName": "WSO2 OpenAI API Key",
      "description": "string",
      "type": "GENERIC",
      "provider": "IN_BUILT",
      "status": "ACTIVE",
      "hash": "hmac-sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe04294e576d4b3d4c57e3f428a",
      "createdBy": "john.doe",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "pagination": {
    "total": 10,
    "offset": 0,
    "limit": 10
  }
}

400 Response

{
  "status": "error",
  "code": "VALIDATION_FAILED",
  "message": "The request failed validation.",
  "errors": [
    {
      "field": "<name of the offending field>",
      "message": "<reason this field failed validation>"
    }
  ]
}

401 Response

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Authorization header is required, or the token is invalid or expired."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred.",
  "trackingId": "4f1c6f2e-8a4b-4c93-b1de-9f2f6f0c2a11"
}

503 Response

{
  "status": "error",
  "code": "SERVICE_UNAVAILABLE",
  "message": "Secrets management is not configured.",
  "trackingId": "4f1c6f2e-8a4b-4c93-b1de-9f2f6f0c2a11"
}

Responses

Status Meaning Description Schema
200 OK List of secret metadata SecretListResponse
400 Bad Request Bad Request. Invalid request or validation error. Error
401 Unauthorized Unauthorized. Authentication credentials are missing or invalid. Error
500 Internal Server Error Internal Server Error. Error
503 Service Unavailable Service Unavailable. The secrets management feature is not configured. Error

Get a secret by handle

GET /secrets/{secretId}

Code samples

curl -X GET https://localhost:9243/api/v0.9/secrets/{secretId} \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Accept: application/json'

Returns metadata for a single secret. The plaintext value is never returned.

Authentication

Parameters

Name In Type Required Description
secretId path string true The secret handle

Example responses

200 Response

{
  "id": "wso2-openai-key",
  "displayName": "WSO2 OpenAI API Key",
  "description": "string",
  "type": "GENERIC",
  "provider": "IN_BUILT",
  "status": "ACTIVE",
  "hash": "hmac-sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe04294e576d4b3d4c57e3f428a",
  "createdBy": "john.doe",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

401 Response

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Authorization header is required, or the token is invalid or expired."
}

404 Response

{
  "status": "error",
  "code": "NOT_FOUND",
  "message": "The specified resource does not exist."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred.",
  "trackingId": "4f1c6f2e-8a4b-4c93-b1de-9f2f6f0c2a11"
}

503 Response

{
  "status": "error",
  "code": "SERVICE_UNAVAILABLE",
  "message": "Secrets management is not configured.",
  "trackingId": "4f1c6f2e-8a4b-4c93-b1de-9f2f6f0c2a11"
}

Responses

Status Meaning Description Schema
200 OK Secret metadata SecretSummary
401 Unauthorized Unauthorized. Authentication credentials are missing or invalid. Error
404 Not Found Not Found. The specified resource does not exist. Error
500 Internal Server Error Internal Server Error. Error
503 Service Unavailable Service Unavailable. The secrets management feature is not configured. Error

Rotate a secret value

PUT /secrets/{secretId}

Code samples

curl -X PUT https://localhost:9243/api/v0.9/secrets/{secretId} \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: multipart/form-data' \
  -H 'Accept: application/json' \
  -F 'id=wso2-openai-key' \
  -F 'displayName=string' \
  -F 'description=string' \
  -F 'value=string'

Re-encrypts and stores a new value for an existing secret. The handle is immutable so all {{ secret "handle" }} placeholder references across resources remain valid without modification.

Authentication

Parameters

Name In Type Required Description
secretId path string true The secret handle
body body SecretUpdateRequest true none

Example responses

200 Response

{
  "id": "wso2-openai-key",
  "displayName": "WSO2 OpenAI API Key",
  "createdBy": "john.doe",
  "updatedBy": "john.doe",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

400 Response

{
  "status": "error",
  "code": "VALIDATION_FAILED",
  "message": "The request failed validation.",
  "errors": [
    {
      "field": "<name of the offending field>",
      "message": "<reason this field failed validation>"
    }
  ]
}

401 Response

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Authorization header is required, or the token is invalid or expired."
}

403 Response

{
  "status": "error",
  "code": "FORBIDDEN",
  "message": "You do not have permission to perform this action."
}

404 Response

{
  "status": "error",
  "code": "NOT_FOUND",
  "message": "The specified resource does not exist."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred.",
  "trackingId": "4f1c6f2e-8a4b-4c93-b1de-9f2f6f0c2a11"
}

503 Response

{
  "status": "error",
  "code": "SERVICE_UNAVAILABLE",
  "message": "Secrets management is not configured.",
  "trackingId": "4f1c6f2e-8a4b-4c93-b1de-9f2f6f0c2a11"
}

Responses

Status Meaning Description Schema
200 OK Secret rotated successfully. SecretResponse
400 Bad Request Bad Request. Invalid request or validation error. Error
401 Unauthorized Unauthorized. Authentication credentials are missing or invalid. Error
403 Forbidden Forbidden. The authenticated user does not have permission to access this resource. Error
404 Not Found Not Found. The specified resource does not exist. Error
500 Internal Server Error Internal Server Error. Error
503 Service Unavailable Service Unavailable. The secrets management feature is not configured. Error

Delete a secret

DELETE /secrets/{secretId}

Code samples

curl -X DELETE https://localhost:9243/api/v0.9/secrets/{secretId} \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Accept: application/json'

Soft-deletes a secret by marking it as DEPRECATED. Returns 409 if the secret is still referenced by any LLM provider or API configuration.

Authentication

Parameters

Name In Type Required Description
secretId path string true The secret handle

Example responses

401 Response

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Authorization header is required, or the token is invalid or expired."
}

403 Response

{
  "status": "error",
  "code": "FORBIDDEN",
  "message": "You do not have permission to perform this action."
}

404 Response

{
  "status": "error",
  "code": "NOT_FOUND",
  "message": "The specified resource does not exist."
}

409 Response

{
  "status": "error",
  "code": "SECRET_IN_USE",
  "message": "The secret is referenced by one or more active resources.",
  "details": {
    "references": [
      {
        "type": "llm_provider",
        "handle": "wso2-openai-provider",
        "name": "WSO2 OpenAI Provider"
      }
    ]
  }
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred.",
  "trackingId": "4f1c6f2e-8a4b-4c93-b1de-9f2f6f0c2a11"
}

503 Response

{
  "status": "error",
  "code": "SERVICE_UNAVAILABLE",
  "message": "Secrets management is not configured.",
  "trackingId": "4f1c6f2e-8a4b-4c93-b1de-9f2f6f0c2a11"
}

Responses

Status Meaning Description Schema
204 No Content Secret deleted successfully None
401 Unauthorized Unauthorized. Authentication credentials are missing or invalid. Error
403 Forbidden Forbidden. The authenticated user does not have permission to access this resource. Error
404 Not Found Not Found. The specified resource does not exist. Error
409 Conflict Conflict. The secret is referenced by one or more active resources. Error
500 Internal Server Error Internal Server Error. Error
503 Service Unavailable Service Unavailable. The secrets management feature is not configured. Error