| name | secure-agent |
| description | Secure an agent by applying a policy from the catalog. Handles multiple
starting points: from an existing API Manager instance, from an agent asset
in Exchange, or from scratch by publishing the agent first. Use when the user
wants to secure an agent, add rate limiting, apply OAuth2, enforce IP
allowlisting, or protect any agent with a policy — regardless of where they
are in the setup process.
|
Secure Agent
Overview
Applies a security or traffic management policy to an agent and deploys it to a self-managed Omni Gateway, walking through the full process from identifying the target agent to selecting a policy, configuring it, and deploying. Supports multiple starting points depending on what the user already has set up — an API Manager instance, an Exchange asset, or just an agent specification.
What you'll build: A fully configured policy enforced on your agent instance, deployed to a Omni Gateway
Architecture
sequenceDiagram
participant User
participant Exchange
participant API Manager
participant Omni Gateway
participant Policy Catalog
User->>Exchange: Publish Agent spec
User->>Exchange: Find Agent asset
Exchange-->>User: groupId, assetId, version
User->>API Manager: Create Instance
API Manager-->>User: instanceId
User->>Omni Gateway: Deploy Instance
Omni Gateway-->>User: Deployment active
User->>Policy Catalog: Browse compatible policies
Policy Catalog-->>User: Policy template + config schema
User->>API Manager: Apply policy with config
API Manager-->>Omni Gateway: Policy enforced
Prerequisites
Before starting, ensure you have:
-
Authentication ready
- Valid Bearer token for Anypoint Platform. If you only have username/password, call
createLogin (POST /accounts/login) from the urn:api:access-management API with body {"username":"...","password":"..."} to obtain a Bearer token first.
- API Manager permissions: View APIs Configuration and Manage Policies scopes
-
Organization Id
- Call
listMe (GET /accounts/api/me) from urn:api:access-management to get your organization ID
- Extract
organizationId from $.user.organization.id in the response
- This is used to list environments, browse the policy catalog, check Exchange, etc.
-
One of the following
- An API instance already in API Manager for the agent (skip to Step 3, then Step 7)
- An agent asset already in Exchange (skip to Step 2)
- An agent specification that needs to be published first (start at Step 1)
Choose Your Path
flowchart TD
Start{What do you have?} -->|Agent spec only| Full[Full Setup]
Start -->|Asset in Exchange| FromExchange[From Exchange]
Start -->|API Manager instance| PolicyOnly[Apply Policy Only]
Full --> S1[Step 1: Publish to Exchange]
S1 --> S2[Step 2: Find in Exchange]
FromExchange --> S2
S2 --> S3[Step 3: Select Environment]
S3 --> S4[Step 4: Select Gateway Target]
S4 --> S5[Step 5: Create API Instance]
S5 --> S6[Step 6: Deploy to Gateway]
PolicyOnly --> S3b[Step 3: Select Environment]
S3b --> S7[Step 7: List Agent Instances]
S6 --> S8[Step 8: Browse Policies]
S7 --> S8
S8 --> S9[Step 9: Apply Policy]
S9 --> Done[✓ Agent Secured]
Execution Paths
This skill has multiple execution paths depending on what you already have:
-
Full setup: Steps 1, 2, 3, 4, 5, 6, 8, 9
- When: You have an agent specification and need to publish it to Exchange first
- You'll need:
organizationId, agent specification file
-
From Exchange asset: Steps 2, 3, 4, 5, 6, 8, 9
- When: The agent is already published in Exchange and you need to find it and create an API Manager instance
- You'll need:
organizationId
-
Apply policy only: Steps 3, 7, 8, 9
- When: You already have an API Manager instance for the agent and want to apply a policy
- You'll need:
organizationId
Step 1: Publish Agent to Exchange
Publishes your agent specification to Exchange as a reusable asset. This makes it available for API Manager to create managed instances from it.
What you'll need:
- Organization ID
- Agent specification file
- Asset name, groupId, assetId, and version
Action: Create a new asset in Exchange with your agent specification.
api: urn:api:exchange-experience
operationId: createAssets
inputs:
organizationId:
from:
api: urn:api:access-management
operation: listMe
field: $.user.organization.id
description: Your organization's Business Group GUID
groupId:
userProvided: true
description: The group ID for the asset (typically matches your organization ID)
example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
assetId:
userProvided: true
description: A unique identifier for the asset in kebab-case
example: "my-agent"
version:
userProvided: true
description: Semantic version for the asset
example: "1.0.0"
outputs:
- name: groupId
path: $.groupId
description: The group ID of the published asset
- name: assetId
path: $.assetId
description: The asset ID of the published asset
- name: assetVersion
path: $.version
description: The version of the published asset
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.
Step 2: Find Agent in Exchange
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 you'll need:
- Valid Bearer token (from Prerequisites)
Action: Search Exchange filtering by agent asset type and select the target agent.
api: urn:api:exchange-experience
operationId: getAssetsSearch
inputs:
types:
value: "agent"
description: Filter for agent assets only
outputs:
- name: groupId
path: $[*].groupId
labels: $[*].name
description: Group ID of the selected agent asset
- name: assetId
path: $[*].assetId
description: Asset ID of the selected agent asset
- name: assetVersion
path: $[*].version
description: Version of the selected agent asset
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.
Step 3: List Environments
List all environments in the organization so you can confirm or select the one where your agent instance will live.
What you'll need:
Action: List available environments and select the target.
api: urn:api:access-management
operationId: listEnvironments
inputs:
organizationId:
from:
api: urn:api:access-management
operation: listMe
field: $.user.organization.id
description: Organization ID from Prerequisites
outputs:
- name: environmentId
path: $.data[*].id
labels: $.data[*].name
description: Selected environment ID (e.g., Production, Sandbox)
What happens next: With the environment selected, you can create an API instance or browse policies.
Step 4: Select Deployment Target
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 you'll need:
- Organization ID and Environment ID
Action: List gateway targets and select the Omni Gateway where the agent will run. Prefer a target with status: "RUNNING".
api: urn:api:api-portal-xapi
operationId: getGatewayTargets
inputs:
organizationId:
from:
api: urn:api:access-management
operation: listMe
field: $.user.organization.id
description: Organization ID
environmentId:
from:
variable: environmentId
description: Environment ID from Step 3
outputs:
- name: targetId
path: $.rows[*].id
labels: $.rows[*].name
description: Selected gateway target ID
- name: targetName
path: $.rows[*].name
description: Name of the selected gateway target
- name: gatewayVersion
value: "1.0.0"
description: Gateway version to use for deployment. The targets response may return "-" instead of a real version; use "1.0.0" as the default.
What happens next: You have a deployment target and its gateway version. Next, create the API instance and then configure its deployment target.
Step 5: Create API Manager Instance
Creates a managed API instance in API Manager from your agent Exchange asset. This creates the API configuration; deployment to the Omni Gateway happens in Step 6.
Important: For Omni Gateway instances, isCloudHub must be null (not false). Setting it to false causes a validation error.
What you'll need:
- Organization ID and Environment ID
- Exchange asset coordinates (groupId, assetId, version)
Action: Create an API instance in the target environment.
api: urn:api:api-manager
operationId: createOrganizationsEnvironmentsApis
inputs:
organizationId:
from:
api: urn:api:access-management
operation: listMe
field: $.user.organization.id
description: Your organization's Business Group GUID
environmentId:
from:
variable: environmentId
description: Target environment ID from Step 3
groupId:
from:
variable: groupId
description: Exchange asset group ID from Step 2
assetId:
from:
variable: assetId
description: Exchange asset ID from Step 2
assetVersion:
from:
variable: assetVersion
description: Exchange asset version from Step 2
instanceLabel:
userProvided: true
description: A human-readable label for this API instance (e.g., "my-agent-v1")
example: "my-agent-v1"
technology:
value: "flexGateway"
description: Gateway technology — this skill targets Omni Gateway deployments
endpoint.isCloudHub:
value: null
description: "Must be null for flexGateway technology (not false — false causes a validation error)"
endpoint.proxyUri:
userProvided: true
description: "The proxy listener URI. Ask the user which port the Omni Gateway should listen on, then use http://0.0.0.0:<port>/"
example: "http://0.0.0.0:8081/"
endpoint.uri:
userProvided: true
optional: true
description: The upstream backend URL for the agent. Ask the user if they want to provide it now or configure it later.
example: "https://backend.example.com/agent/v1"
outputs:
- name: environmentApiId
path: $.id
description: The API instance ID in API Manager
What happens next: The API instance exists but is not yet deployed. Next, deploy it to the Omni Gateway target selected in Step 4.
Step 6: Deploy to Omni Gateway
Deploys the API instance to the selected Omni 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 Omni Gateway deployments.
What you'll need:
- Organization ID, Environment ID, and API instance ID from Step 5
- Deployment target ID and gateway version from Step 4
Action: Create a deployment for the API instance on the selected Omni Gateway.
api: urn:api:proxies-xapi
operationId: createOrganizationsByOrganizationidEnvironmentsByEnvironmentidApisByEnvironmentapiidDeployments
inputs:
organizationId:
from:
api: urn:api:access-management
operation: listMe
field: $.user.organization.id
description: Organization ID
environmentId:
from:
variable: environmentId
description: Environment ID from Step 3 (used in both the URL path and the request body for HY deployment type)
environmentApiId:
from:
variable: environmentApiId
description: API instance ID from Step 5
type:
value: "HY"
description: "Deployment type for self-managed Omni Gateway (HY = Hybrid)"
targetId:
from:
variable: targetId
description: Omni Gateway target ID from Step 4
targetName:
from:
variable: targetName
description: Omni Gateway target name from Step 4
gatewayVersion:
value: "1.0.0"
description: "Gateway version for deployment. Use \"1.0.0\" as the default."
overwrite:
value: false
description: "Whether to overwrite an existing deployment"
outputs:
- name: deploymentId
path: $.id
description: The ID of the proxy deployment
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 Omni 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 Omni 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.
Step 7: List Agent Instances
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 you'll need:
- Organization ID and Environment ID
Action: List agent instances and select the target.
api: urn:api:api-manager
operationId: listOrganizationsEnvironmentsApis
inputs:
organizationId:
from:
api: urn:api:access-management
operation: listMe
field: $.user.organization.id
description: Organization ID
environmentId:
from:
variable: environmentId
description: Environment ID from Step 3
family:
value: "agentic"
description: Filter for agent (agentic) instances only
outputs:
- name: environmentApiId
path: $.assets[*].apis[*].id
labels: $.assets[*].apis[*].autodiscoveryInstanceName
description: The agent instance ID in API Manager
What happens next: You have the agent instance ID. Next, browse the policy catalog to select which policy to apply.
Step 8: Browse Exchange Policy Catalog
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 you'll need:
- Organization ID
- Environment ID and API instance ID (to filter for compatible templates)
Action: List Exchange policy templates and select the one to apply. Pass apiInstanceId and environmentId to filter for templates compatible with your agent's gateway type (e.g., Omni Gateway, Mule Gateway).
api: urn:api:api-portal-xapi
operationId: getExchangePolicyTemplates
inputs:
organizationId:
from:
api: urn:api:access-management
operation: listMe
field: $.user.organization.id
description: Organization ID
apiInstanceId:
from:
variable: environmentApiId
description: API instance ID from Step 5 or Step 7 (filters for compatible templates)
environmentId:
from:
variable: environmentId
description: Environment ID from Step 3
latest:
value: "true"
description: Return only the latest version of each template
includeConfiguration:
value: "true"
description: Include the configuration schema for each template
outputs:
- name: policyGroupId
path: $[*].groupId
labels: $[*].assetId
description: Exchange group ID of the selected policy template
- name: policyAssetId
path: $[*].assetId
description: Exchange asset ID of the selected policy template
- name: policyAssetVersion
path: $[*].version
description: Exchange version of the selected policy template (gateway-compatible)
- name: policyConfiguration
path: $[*].configuration
description: Configuration schema with gateway-compatible property names and defaults
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.
Step 9: Apply Policy to Instance
Apply the selected policy to your agent instance with the appropriate configuration. Use the Exchange coordinates and configuration property names from Step 8.
What you'll need:
- Organization ID, Environment ID, and API instance ID
- Policy Exchange coordinates (groupId, assetId, assetVersion) from Step 8
- Policy configuration based on the schema from Step 8's
policyConfiguration output
Action: Apply the policy to your API instance. Build the configurationData object using the property names from Step 8's configuration schema. For each configuration property, present the user with the property name, its description, and the default value, then ask if they want to keep the default or provide a custom value. If a property has no default, always ask the user for a value.
api: urn:api:api-manager
operationId: createOrganizationsEnvironmentsApisPolicies
inputs:
organizationId:
from:
api: urn:api:access-management
operation: listMe
field: $.user.organization.id
description: Organization ID
environmentId:
from:
variable: environmentId
description: Environment ID from Step 3
environmentApiId:
from:
variable: environmentApiId
description: API instance ID from Step 5 or Step 7 (or provided manually)
groupId:
from:
variable: policyGroupId
description: Policy Exchange group ID from Step 8
assetId:
from:
variable: policyAssetId
description: Policy Exchange asset ID from Step 8
assetVersion:
from:
variable: policyAssetVersion
description: Policy Exchange version from Step 8
outputs:
- name: policyId
path: $.id
description: The ID of the applied policy instance
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 Omni 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, Omni 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.
Completion Checklist
After completing all steps, verify:
What You've Built
Your agent is now protected with:
- Policy enforcement — Selected policy is active on your agent instance. All incoming traffic is evaluated against policy rules.
- Bound to Omni Gateway — API instance is created with deployment configuration targeting a self-managed Omni Gateway. The Omni Gateway picks up the configuration automatically.
- Managed configuration — Policy settings are version-controlled in API Manager. Configuration can be updated without redeploying the agent.
Next Steps
-
Test the policy
- Send test requests to verify the policy is enforcing correctly
- Check that authorized requests pass and unauthorized ones are blocked
-
Add more policies
- Run this skill again to layer additional policies (e.g., rate limiting + OAuth2)
- Policy ordering matters — adjust priority in API Manager if needed
-
Monitor policy activity
- Check API Manager analytics for policy enforcement metrics
- Set up alerts for unusual rejection patterns
Tips and Best Practices
Policy Selection
- Rate Limiting: Use when you need to control traffic volume per client
- OAuth 2.0: Use for token-based authentication and authorization
- IP Allowlist/Blocklist: Use to restrict access by network origin
- Client ID Enforcement: Use to require registered client applications
Policy Ordering
- Authentication policies should be applied first (lowest order number)
- Rate limiting should come after authentication
- Transformation policies should be last
Gateway Compatibility
- Always use
getExchangePolicyTemplates with apiInstanceId to get gateway-compatible templates
- Configuration property names and defaults vary by gateway type (Omni Gateway vs. Mule Gateway)
- The Exchange template version may differ from the generic template version
Agent Discovery
- The Exchange search in Step 2 is not org-scoped — it returns all agents visible to the authenticated user
- Use the asset
name field to identify the correct agent when multiple results are returned
- If you published the agent in Step 1, its coordinates are already available — Step 2 can be used to confirm
Troubleshooting
Policy Not Enforcing
Symptoms: Requests pass through without policy evaluation
Possible causes:
- API instance is not deployed or is in an error state
- Policy configuration has a permissive default that allows all traffic
- Policy is applied but not yet propagated (wait 1-2 minutes)
Solutions:
- Check API instance status in API Manager
- Review policy configuration for overly permissive settings
- Wait for propagation and retry
Policy Blocks All Requests
Symptoms: All requests return 401 or 403, even legitimate ones
Possible causes:
- Policy configuration is too restrictive
- Required credentials are not being sent correctly
- Policy expects headers or parameters in a specific format
Solutions:
- Review the policy configuration schema for required fields
- Check that client applications are sending credentials in the expected format
- Temporarily disable the policy to isolate the issue
400 Error When Applying Policy
Symptoms: "The policy to be created is missing at least one of the following properties related to the policy template: 'groupId', 'assetId', 'assetVersion'."
Possible causes:
- Used the generic
listOrganizationsPolicytemplates endpoint which does not return Exchange coordinates
Solutions:
- Use
getExchangePolicyTemplates from api-portal-xapi instead — this returns the full Exchange coordinates needed by the apply endpoint
Agent Not Found in Exchange
Symptoms: Step 2 returns an empty list
Possible causes:
- The agent has not been published to Exchange yet
- The asset type is not
agent
Solutions:
- Start from Step 1 to publish the agent to Exchange first
- Verify the asset was published with the correct type
Related Jobs
- secure-api: The equivalent skill for securing standard APIs with policies
- secure-mcp-server: The equivalent skill for securing MCP servers with policies
- apply-policy-to-api-instance: Apply a policy when you already have an API instance (simpler flow)
