AI Workspace
next
References
Platform API

Gateway Policies¶

Custom gateway policy management operations

Get synced custom policies for the current organization¶

GET /gateway-custom-policies

Code samples

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

Returns all custom policies synced to the current organization (from the JWT organization claim).

Authentication¶

This operation requires a Bearer JWT access token in the Authorization header. Required scopes (the token must carry at least one of): `ap:gateway_custom_policy:read`, `ap:gateway_custom_policy:manage`

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.

Example responses

200 Response

{
  "count": 0,
  "list": [
    {
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "organizationUuid": "bc554ded-7e40-44a7-b397-48480793ad03",
      "name": "rate-limit-custom",
      "version": "1.0.0",
      "description": "Custom rate limiting policy",
      "policyDefinition": {},
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "pagination": {
    "total": 10,
    "offset": 0,
    "limit": 10
  }
}

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

Responses

Status	Meaning	Description	Schema
200	OK	List of custom policies	CustomPolicyListResponse
401	Unauthorized	Unauthorized. Authentication credentials are missing or invalid.	Error
500	Internal Server Error	Internal Server Error.	Error

Sync a custom policy from the gateway manifest¶

POST /gateway-custom-policies/sync

Code samples

curl -X POST https://localhost:9243/api/v0.9/gateway-custom-policies/sync?gatewayId=prod-gateway-01&policyName=set-wso2-headers&policyVersion=1.0.0 \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Accept: application/json'

Syncs a custom policy from the gateway manifest into the organization's custom policy registry. Version-based rules apply: - New major version: creates a new policy record (e.g. v1.x.x and v2.x.x coexist). - New minor version (same major): updates the existing record (e.g. v1.1.0 → v1.2.0). - Patch version change (same major.minor): not allowed. - Downgrade: not allowed. Policy names are case-insensitive. After syncing, the policy can be applied to APIs in the organization.

Authentication¶

This operation requires a Bearer JWT access token in the Authorization header. Required scopes (the token must carry at least one of): `ap:gateway_custom_policy:create`, `ap:gateway_custom_policy:manage`

Parameters

Name	In	Type	Required	Description
gatewayId	query	string	true	Handle (URL-friendly slug) of the gateway whose manifest contains the policy
policyName	query	string	true	Name of the custom policy (case-insensitive)
policyVersion	query	string	true	Version of the custom policy in MAJOR.MINOR.PATCH format

Example responses

200 Response

{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "organizationUuid": "bc554ded-7e40-44a7-b397-48480793ad03",
  "name": "rate-limit-custom",
  "version": "1.0.0",
  "description": "Custom rate limiting policy",
  "policyDefinition": {},
  "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."
}

409 Response

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

422 Response

{
  "status": "error",
  "code": "POLICY_INVALID_STATE",
  "message": "The policy is not a custom policy, or its manifest is unavailable."
}

500 Response

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

Responses

Status	Meaning	Description	Schema
200	OK	Custom policy synced successfully	CustomPolicyResponse
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
409	Conflict	Conflict. The request conflicts with the current state of the resource.	Error
422	Unprocessable Entity	Policy is not a custom policy or manifest is unavailable	Error
500	Internal Server Error	Internal Server Error.	Error

Get a specific custom policy version¶

GET /gateway-custom-policies/{gatewayCustomPolicyId}/versions/{version}

Code samples

curl -X GET https://localhost:9243/api/v0.9/gateway-custom-policies/{gatewayCustomPolicyId}/versions/{version} \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Accept: application/json'

Returns a custom policy by its UUID and version for the current organization.

Authentication¶

This operation requires a Bearer JWT access token in the Authorization header. Required scopes (the token must carry at least one of): `ap:gateway_custom_policy:read`, `ap:gateway_custom_policy:manage`

Parameters

Name	In	Type	Required	Description
gatewayCustomPolicyId	path	string(uuid)	true	UUID of the custom policy record
version	path	string	true	Version of the custom policy (e.g. "1.0.0")

Example responses

200 Response

{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "organizationUuid": "bc554ded-7e40-44a7-b397-48480793ad03",
  "name": "rate-limit-custom",
  "version": "1.0.0",
  "description": "Custom rate limiting policy",
  "policyDefinition": {},
  "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"
}

Responses

Status	Meaning	Description	Schema
200	OK	Custom policy retrieved successfully	CustomPolicyResponse
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

Delete a specific custom policy version¶

DELETE /gateway-custom-policies/{gatewayCustomPolicyId}/versions/{version}

Code samples

curl -X DELETE https://localhost:9243/api/v0.9/gateway-custom-policies/{gatewayCustomPolicyId}/versions/{version} \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Accept: application/json'

Deletes a custom policy by its UUID and version. The policy must not be in use by any APIs.

Authentication¶

This operation requires a Bearer JWT access token in the Authorization header. Required scopes (the token must carry at least one of): `ap:gateway_custom_policy:delete`, `ap:gateway_custom_policy:manage`

Parameters

Name	In	Type	Required	Description
gatewayCustomPolicyId	path	string(uuid)	true	UUID of the custom policy record
version	path	string	true	Version of the custom policy (e.g. "1.0.0")

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": "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"
}

Responses

Status	Meaning	Description	Schema
204	No Content	Custom policy 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 request conflicts with the current state of the resource.	Error
500	Internal Server Error	Internal Server Error.	Error