Gateways

Gateway registration and management operations

Register a new gateway

POST /gateways

Code samples

curl -X POST https://localhost:9243/api/v0.9/gateways \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d @payload.json

Creates a new gateway within the organization specified in the JWT token. Organization ID is automatically extracted from the token and does not need to be provided.

Payload

{
  "id": "prod-gateway-01",
  "displayName": "Production Gateway 01",
  "description": "Production gateway for handling API traffic",
  "endpoints": [
    "https://api.example.com:8443/api/v1",
    "wss://events.example.com:8444"
  ],
  "isCritical": true,
  "functionalityType": "regular",
  "properties": {
    "region": "us-west",
    "tier": "premium"
  },
  "version": "1.0"
}

Authentication

Parameters

Name	In	Type	Required	Description
body	body	CreateGatewayRequest	true	Gateway registration details

Example responses

201 Response

{
  "id": "prod-gateway-01",
  "organizationId": "acme",
  "displayName": "Production Gateway 01",
  "description": "Production gateway for handling API traffic",
  "properties": {
    "region": "us-west",
    "tier": "premium"
  },
  "endpoints": [
    "https://api.example.com:8443/api/v1",
    "wss://events.example.com:8444"
  ],
  "isCritical": true,
  "functionalityType": "regular",
  "version": "1.0",
  "isActive": true,
  "createdBy": "john.doe",
  "updatedBy": "john.doe",
  "createdAt": "2025-10-14T10:30:00Z",
  "updatedAt": "2025-10-14T10:30:00Z"
}

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

500 Response

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

Responses

Status	Meaning	Description	Schema
201	Created	Gateway registered successfully	GatewayResponse
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
500	Internal Server Error	Internal Server Error.	Error

Response Headers

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

List all gateways

GET /gateways

Code samples

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

Retrieves a list of all registered gateways for the organization specified in the JWT token. Organization ID is automatically extracted from the token.

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.
sortBy	query	string	false	Field to sort the collection by. An unrecognized value falls back to the default sort (createdAt).
sortOrder	query	string	false	Sort direction applied to sortBy.
query	query	string	false	Case-insensitive substring filter matched against the resource id (handle).

Enumerated Values

Parameter	Value
sortBy	name
sortBy	createdAt
sortOrder	asc
sortOrder	desc

Example responses

200 Response

{
  "count": 2,
  "list": [
    {
      "id": "prod-gateway-01",
      "organizationId": "acme",
      "displayName": "Production Gateway 01",
      "description": "Production gateway for handling API traffic",
      "properties": {
        "region": "us-west",
        "tier": "premium"
      },
      "endpoints": [
        "https://api.example.com:8443/api/v1",
        "wss://events.example.com:8444"
      ],
      "isCritical": true,
      "functionalityType": "regular",
      "version": "1.0",
      "isActive": true,
      "createdBy": "john.doe",
      "updatedBy": "john.doe",
      "createdAt": "2025-10-14T10:30:00Z",
      "updatedAt": "2025-10-14T10:30:00Z"
    }
  ],
  "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"
}

Responses

Status	Meaning	Description	Schema
200	OK	Gateways retrieved successfully	GatewayListResponse
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

Get gateway by ID

GET /gateways/{gatewayId}

Code samples

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

Retrieves a specific gateway by its ID (handle). Access is validated against the organization in the JWT token.

Authentication

Parameters

Name	In	Type	Required	Description
gatewayId	path	string	true	Gateway ID consisting of the handle (unique slug identifier) of the Gateway.

Detailed descriptions

gatewayId: Gateway ID consisting of the handle (unique slug identifier) of the Gateway.

Example responses

200 Response

{
  "id": "prod-gateway-01",
  "organizationId": "acme",
  "displayName": "Production Gateway 01",
  "description": "Production gateway for handling API traffic",
  "properties": {
    "region": "us-west",
    "tier": "premium"
  },
  "endpoints": [
    "https://api.example.com:8443/api/v1",
    "wss://events.example.com:8444"
  ],
  "isCritical": true,
  "functionalityType": "regular",
  "version": "1.0",
  "isActive": true,
  "createdBy": "john.doe",
  "updatedBy": "john.doe",
  "createdAt": "2025-10-14T10:30:00Z",
  "updatedAt": "2025-10-14T10:30:00Z"
}

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

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	Gateway retrieved successfully	GatewayResponse
400	Bad Request	Bad Request. Invalid request or validation error.	Error
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

Update gateway

PUT /gateways/{gatewayId}

Code samples

curl -X PUT https://localhost:9243/api/v0.9/gateways/{gatewayId} \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d @payload.json

Updates an existing gateway's mutable fields (description). Access is validated against the organization in the JWT token.

Payload

{
  "organizationId": "acme",
  "displayName": "Production Gateway 01",
  "description": "Production gateway for handling API traffic",
  "properties": {
    "region": "us-west",
    "tier": "premium"
  },
  "endpoints": [
    "https://api.example.com:8443/api/v1",
    "wss://events.example.com:8444"
  ],
  "isCritical": true,
  "functionalityType": "regular",
  "version": "1.0",
  "isActive": true,
  "createdAt": "2025-10-14T10:30:00Z",
  "updatedAt": "2025-10-14T10:30:00Z"
}

Authentication

Parameters

Name	In	Type	Required	Description
gatewayId	path	string	true	Gateway ID consisting of the handle (unique slug identifier) of the Gateway.
body	body	GatewayResponse	true	Gateway object that needs to be updated

Detailed descriptions

gatewayId: Gateway ID consisting of the handle (unique slug identifier) of the Gateway.

Example responses

200 Response

{
  "id": "prod-gateway-01",
  "organizationId": "acme",
  "displayName": "Production Gateway 01",
  "description": "Production gateway for handling API traffic",
  "properties": {
    "region": "us-west",
    "tier": "premium"
  },
  "endpoints": [
    "https://api.example.com:8443/api/v1",
    "wss://events.example.com:8444"
  ],
  "isCritical": true,
  "functionalityType": "regular",
  "version": "1.0",
  "isActive": true,
  "createdBy": "john.doe",
  "updatedBy": "john.doe",
  "createdAt": "2025-10-14T10:30:00Z",
  "updatedAt": "2025-10-14T10:30:00Z"
}

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

Responses

Status	Meaning	Description	Schema
200	OK	Gateway updated successfully	GatewayResponse
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

Delete gateway

DELETE /gateways/{gatewayId}

Code samples

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

Permanently deletes a gateway and all associated tokens (CASCADE). Deletion is blocked if the gateway has active API deployments or WebSocket connections. Access is validated against the organization in the JWT token.

Authentication

Parameters

Name	In	Type	Required	Description
gatewayId	path	string	true	Gateway ID consisting of the handle (unique slug identifier) of the Gateway.

Detailed descriptions

gatewayId: Gateway ID consisting of the handle (unique slug identifier) of the Gateway.

Example responses

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

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	Gateway deleted successfully	None
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
500	Internal Server Error	Internal Server Error.	Error

Get gateway policy manifest

GET /gateways/{gatewayId}/manifest

Code samples

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

Returns the policy manifest for the specified gateway. The manifest is populated by the gateway controller when it connects to the platform API, and contains all installed policies. Custom policies additionally include their full policy definition schema.

Authentication

Parameters

Name	In	Type	Required	Description
gatewayId	path	string	true	Gateway ID consisting of the handle (unique slug identifier) of the Gateway.

Detailed descriptions

gatewayId: Gateway ID consisting of the handle (unique slug identifier) of the Gateway.

Example responses

200 Response

{
  "policies": [
    {
      "name": "set-wso2-headers",
      "version": "v0.8.0",
      "description": "Sets WSO2-specific headers in the request and response.",
      "isCustomPolicy": true,
      "policyDefinition": {}
    }
  ]
}

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	Gateway policy manifest	ManifestSyncResponse
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