Protect Agent With Policies

Publishes your agent specification to Exchange as a reusable asset. This makes it available for API Manager to create managed instances from it.

What happens next: Your agent specification is now available in Exchange. Next, you can search for it to confirm and extract the coordinates needed for API Manager.

Search Exchange for agent assets. This search is not scoped to a specific organization — it returns all agent assets visible to the authenticated user across all organizations.

What happens next: You have the Exchange coordinates (groupId, assetId, version) for the agent. Next, select an environment where the API instance will be created.

List all environments in the organization so you can confirm or select the one where your agent instance will live.

What happens next: With the environment selected, you can create an API instance or browse policies.

List available gateway targets registered in the environment. You need the target ID and gateway version before creating the API instance, because the deployment configuration is set via a PATCH after creation.

What happens next: You have a deployment target and its gateway version. Next, create the API instance and then configure its deployment target.

Creates a managed API instance in API Manager from your agent Exchange asset. This creates the API configuration; deployment to the Flex Gateway happens in Step 6.

Important: For Flex Gateway instances, isCloudHub must be null (not false). Setting it to false causes a validation error.

What happens next: The API instance exists but is not yet deployed. Next, deploy it to the Flex Gateway target selected in Step 4.

Deploys the API instance to the selected Flex Gateway target. This uses the Proxies API deployment endpoint with flat top-level fields — do not use the nested target object, which requires additional fields that are not needed for self-managed Flex Gateway deployments.

Request body structure: Use flat top-level fields, not the nested target object:

{
  "type": "HY",
  "targetId": "<from Step 4>",
  "targetName": "<from Step 4>",
  "gatewayVersion": "1.0.0",
  "environmentId": "<from Step 3>",
  "overwrite": false
}

What happens next: The agent instance is now deployed to the Flex Gateway. Next, browse the policy catalog to select which policy to apply.

Common issues:

• "Field environmentId is required for deployment type HY": The environmentId must be in the request body, not just the URL path parameter.
• "Field gatewayVersion is required for deployment type HY": Use the version from the getGatewayTargets response (Step 4). Using an incorrect version causes policy implementation errors.
• "Policy implementations cannot be set because runtime version is unknown": The gatewayVersion value doesn't match a known Flex Gateway version. Verify the version from the target's actual runtime version in Step 4.
• 409 Conflict: The agent may already be deployed to this target. List existing deployments with GET .../deployments first to check.

Lists agent instances in the selected environment by filtering with family=agentic. Use this step when you already have an API Manager instance for the agent and need to find its ID to apply a policy.

What happens next: You have the agent instance ID. Next, browse the policy catalog to select which policy to apply.

List all available policy templates from Exchange for your organization. This endpoint returns the full Exchange coordinates (groupId, assetId, assetVersion) and gateway-compatible configuration for each template — these are required when applying a policy.

Important: Use the api-portal-xapi endpoint (getExchangePolicyTemplates) instead of the generic listOrganizationsPolicytemplates endpoint. The generic endpoint does not return Exchange coordinates or gateway-specific configuration property names, which are required for the apply step.

What happens next: You have the policy template's Exchange coordinates and its configuration schema with the correct property names for your gateway type. Review the policyConfiguration output to understand what settings the policy accepts before applying it.

Common issues:

• Empty list: Pass apiInstanceId and environmentId to get templates compatible with your gateway type. Without these filters, some templates may not appear.
• Wrong config property names: Always use the configuration from this endpoint — the generic listOrganizationsPolicytemplates endpoint may return different (non-gateway-compatible) property names and defaults.

Apply the selected policy to your agent instance with the appropriate configuration. Use the Exchange coordinates and configuration property names from Step 8.

What happens next: Your agent is now protected with the selected policy. Since the API instance was configured with deployment information in Step 6, the policy is active and enforcing on the Flex Gateway.

Common issues:

• 400 Bad Request — missing groupId/assetId/assetVersion: The apply endpoint requires full Exchange coordinates, not just a template ID. Make sure you used getExchangePolicyTemplates (Step 8) to get these values.
• 400 Bad Request — invalid configurationData: The configuration property names differ between gateway types. Use the property names from Step 8's policyConfiguration output, not from the generic template endpoint. For example, Flex Gateway uses credentialsOriginHasHttpBasicAuthenticationHeader while the generic template uses credentialsOrigin.
• 409 Conflict: A policy of this type may already be applied to the API instance. List existing policies first to check, or add ?allowDuplicated=true to the request URL to apply a second instance of the same policy type.
• 403 Forbidden: You need Manage Policies permission in the target environment.