Skip to content

secrets-management.md

Latest commit

 

History

History
424 lines (318 loc) · 11 KB

secrets-management.md

File metadata and controls

424 lines (318 loc) · 11 KB

Secrets Management

CRUD operations for Secrets

List all secrets

GET /secrets

Code samples

curl -X GET http://localhost:9090/api/management/v0.9/secrets \
  -u {username}:{password} \
  -H 'Accept: application/json'

Retrieve a list of all stored secrets. Returns secret identifiers without the actual secret values for security purposes.

Authentication

This operation requires Basic Auth authentication.

Required roles: admin

Example responses

200 Response

{
  "status": "success",
  "count": 5,
  "secrets": [
    {
      "apiVersion": "gateway.api-platform.wso2.com/v1alpha1",
      "kind": "Secret",
      "metadata": {
        "name": "database-password"
      },
      "spec": {
        "displayName": "Database Password"
      },
      "status": {
        "id": "database-password",
        "createdAt": "2026-04-24T07:21:13Z",
        "updatedAt": "2026-04-24T07:21:13Z"
      }
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK List of secrets retrieved successfully SecretListResponse
401 Unauthorized Unauthorized - authentication required ErrorResponse
500 Internal Server Error Internal server error ErrorResponse

Create a new secret

POST /secrets

Code samples

curl -X POST http://localhost:9090/api/management/v0.9/secrets \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d @payload.json

Stores a new secret encrypted at rest. The secret ID must be unique. The value is encrypted using the primary encryption provider before persistence.

Payload

{
  "apiVersion": "gateway.api-platform.wso2.com/v1alpha1",
  "kind": "Secret",
  "metadata": {
    "name": "database-password"
  },
  "spec": {
    "displayName": "Database Password",
    "description": "PostgreSQL main database password",
    "value": "sup3rs3cr3t!"
  }
}

Authentication

This operation requires Basic Auth authentication.

Required roles: admin

Parameters

Name In Type Required Description
body body SecretConfigurationRequest true none

Example responses

Secret created successfully

{
  "apiVersion": "gateway.api-platform.wso2.com/v1alpha1",
  "kind": "Secret",
  "metadata": {
    "name": "database-password"
  },
  "spec": {
    "displayName": "Database Password",
    "description": "PostgreSQL main database password"
  },
  "status": {
    "id": "database-password",
    "createdAt": "2026-01-05T10:30:00Z",
    "updatedAt": "2026-01-05T10:30:00Z"
  }
}

400 Response

{
  "status": "error",
  "message": "Configuration validation failed",
  "errors": [
    {
      "field": "spec.context",
      "message": "Context must start with / and cannot end with /"
    }
  ]
}

Responses

Status Meaning Description Schema
201 Created Secret created successfully SecretConfigurationResponseCreateUpdate
400 Bad Request Bad request - missing or invalid fields ErrorResponse
401 Unauthorized Unauthorized - authentication required ErrorResponse
409 Conflict Conflict - secret with this ID already exists ErrorResponse
500 Internal Server Error Internal server error - encryption failed ErrorResponse

Retrieve a secret

GET /secrets/{id}

Code samples

curl -X GET http://localhost:9090/api/management/v0.9/secrets/{id} \
  -u {username}:{password} \
  -H 'Accept: application/json'

Retrieves and decrypts a secret. The secret value is decrypted using the encryption provider chain before being returned. If all providers fail to decrypt the secret, a 500 error is returned with a generic message.

Authentication

This operation requires Basic Auth authentication.

Required roles: admin

Parameters

Name In Type Required Description
id path string true Unique secret identifier

Example responses

Secret retrieved and decrypted successfully

{
  "apiVersion": "gateway.api-platform.wso2.com/v1alpha1",
  "kind": "Secret",
  "metadata": {
    "name": "database-password"
  },
  "spec": {
    "displayName": "Database Password",
    "description": "PostgreSQL main database password",
    "value": "sup3rs3cr3t!"
  },
  "status": {
    "id": "database-password",
    "createdAt": "2026-01-05T10:30:00Z",
    "updatedAt": "2026-01-05T10:30:00Z"
  }
}

401 Response

{
  "status": "error",
  "message": "Configuration validation failed",
  "errors": [
    {
      "field": "spec.context",
      "message": "Context must start with / and cannot end with /"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Secret retrieved and decrypted successfully SecretConfigurationResponseRetrieved
401 Unauthorized Unauthorized - authentication required ErrorResponse
404 Not Found Secret configuration not found ErrorResponse
500 Internal Server Error Internal server error - decryption failed ErrorResponse

Update a secret

PUT /secrets/{id}

Code samples

curl -X PUT http://localhost:9090/api/management/v0.9/secrets/{id} \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d @payload.json

Updates an existing secret with a new value. The new value is encrypted using the current primary encryption provider, enabling automatic migration to newer keys during updates. Old secrets remain readable via the provider chain.

Payload

{
  "apiVersion": "gateway.api-platform.wso2.com/v1alpha1",
  "kind": "Secret",
  "metadata": {
    "name": "database-password"
  },
  "spec": {
    "displayName": "Database Password",
    "description": "PostgreSQL main database password",
    "value": "sup3rs3cr3t!"
  }
}

Authentication

This operation requires Basic Auth authentication.

Required roles: admin

Parameters

Name In Type Required Description
body body SecretConfigurationRequest true none
id path string true Unique secret identifier

Example responses

Secret updated successfully

{
  "apiVersion": "gateway.api-platform.wso2.com/v1alpha1",
  "kind": "Secret",
  "metadata": {
    "name": "database-password"
  },
  "spec": {
    "displayName": "Database Password",
    "description": "PostgreSQL main database password"
  },
  "status": {
    "id": "database-password",
    "createdAt": "2026-01-05T10:30:00Z",
    "updatedAt": "2026-01-05T11:45:00Z"
  }
}

400 Response

{
  "status": "error",
  "message": "Configuration validation failed",
  "errors": [
    {
      "field": "spec.context",
      "message": "Context must start with / and cannot end with /"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Secret updated successfully SecretConfigurationResponseCreateUpdate
400 Bad Request Bad request - missing or invalid value ErrorResponse
401 Unauthorized Unauthorized - authentication required ErrorResponse
404 Not Found Secret configuration not found ErrorResponse
500 Internal Server Error Internal server error - encryption failed ErrorResponse

Delete a secret

DELETE /secrets/{id}

Code samples

curl -X DELETE http://localhost:9090/api/management/v0.9/secrets/{id} \
  -u {username}:{password} \
  -H 'Accept: application/json'

Permanently deletes a secret from the database. This is a hard delete with no recovery mechanism. The operation is idempotent - deleting a non-existent secret returns 404.

Authentication

This operation requires Basic Auth authentication.

Required roles: admin

Parameters

Name In Type Required Description
id path string true Unique secret identifier

Example responses

401 Response

{
  "status": "error",
  "message": "Configuration validation failed",
  "errors": [
    {
      "field": "spec.context",
      "message": "Context must start with / and cannot end with /"
    }
  ]
}

Secret configuration not found

{
  "status": "not_found",
  "message": "secret configuration not found"
}

Responses

Status Meaning Description Schema
200 OK Secret deleted successfully (no content) None
401 Unauthorized Unauthorized - authentication required ErrorResponse
404 Not Found Secret configuration not found ErrorResponse
500 Internal Server Error Internal server error - database failure ErrorResponse