--- updatedAt: 2026-07-31T12:37:05.000Z --- # Create a new Agent Onboards a new agent in IBM Verify following the SCIM 2.0 Agent schema. Schema: urn:ietf:params:scim:schemas:core:ibm:2.0:Agent **Required Entitlements** (at least one): tenantAdmin, writeAgents, agentOwner ## Mandatory Fields - **schemas** (array): SCIM schema URIs - REQUIRED - **displayName** (string, max 256 chars): Human-readable name for the agent. Must be unique within tenant - REQUIRED ## Optional Fields - **status** (string): Agent status. Values: DEFAULT, ACTIVE, SUSPENDED, UNDER_REVIEW. **Any value provided is silently overridden to `UNDER_REVIEW` on creation.** - **description** (string, max 1024 chars): Detailed description of the agent's purpose - **externalIds** (array): External system identifiers. Each must be unique within tenant. Max 1000 items, each max 128 chars. - **owners** (array): Owner user IDs - **tags** (array): Custom tags for categorization - **authMethods** (array): Authentication methods. Each requires 'name' (unique within agent, max 128 chars) and 'type' (jwt, certificate, oidc, oauth, apikey, mtls, svid-jwt, svid-x509) ## Read-Only Fields - **oauthClients** (array): OAuth clients are READ-ONLY. Fetched dynamically once Agent Id gets associated with OIDC Applications. Cannot be set through POST/PUT. ## Uniqueness Constraints - **displayName**: Must be unique within tenant - **externalIds**: Each externalId must be unique within tenant - **authMethods[].name**: Must be unique within the agent # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "version": "1.0.0", "description": "AI Agents", "title": "AI Agents" }, "servers": [ { "url": "https://{tenanturl}", "variables": { "tenanturl": { "default": "{tenant_url}", "description": "URL of your IBM Security Verify tenant" } } } ], "tags": [ { "name": "Agent management", "description": "SCIM 2.0 compliant agent operations" } ], "paths": { "/v1.0/Agents": { "post": { "tags": [ "Agent management" ], "summary": "Create a new Agent", "description": "Onboards a new agent in IBM Verify following the SCIM 2.0 Agent schema.\n\nSchema: urn:ietf:params:scim:schemas:core:ibm:2.0:Agent\n\n**Required Entitlements** (at least one): tenantAdmin, writeAgents, agentOwner\n\n## Mandatory Fields\n\n- **schemas** (array): SCIM schema URIs - REQUIRED\n- **displayName** (string, max 256 chars): Human-readable name for the agent. Must be unique within tenant - REQUIRED\n\n## Optional Fields\n\n- **status** (string): Agent status. Values: DEFAULT, ACTIVE, SUSPENDED, UNDER_REVIEW. **Any value provided is silently overridden to `UNDER_REVIEW` on creation.**\n- **description** (string, max 1024 chars): Detailed description of the agent's purpose\n- **externalIds** (array): External system identifiers. Each must be unique within tenant. Max 1000 items, each max 128 chars.\n- **owners** (array): Owner user IDs\n- **tags** (array): Custom tags for categorization\n- **authMethods** (array): Authentication methods. Each requires 'name' (unique within agent, max 128 chars) and 'type' (jwt, certificate, oidc, oauth, apikey, mtls, svid-jwt, svid-x509)\n\n## Read-Only Fields\n\n- **oauthClients** (array): OAuth clients are READ-ONLY. Fetched dynamically once Agent Id gets associated with OIDC Applications. Cannot be set through POST/PUT.\n\n## Uniqueness Constraints\n\n- **displayName**: Must be unique within tenant\n- **externalIds**: Each externalId must be unique within tenant\n- **authMethods[].name**: Must be unique within the agent", "requestBody": { "description": "Agent creation request with SCIM 2.0 compliant schema", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CreateAgentRequest" } } }, "required": true }, "responses": { "201": { "description": "Agent created successfully", "content": {} }, "400": { "description": "Bad Request - Invalid request payload (CSINH1002E) or validation errors (CSINH2100E-CSINH2112E)", "content": {} }, "401": { "description": "Unauthorized - Authentication required", "content": {} }, "403": { "description": "Forbidden - Insufficient permissions (CSINH2501E)", "content": {} }, "409": { "description": "Conflict - Agent with same displayName or externalId already exists (CSINH2002E)", "content": {} }, "500": { "description": "Internal Server Error (CSINH1000E)", "content": {} } }, "x-category": "AI Agents", "x-publicAPI": "true", "x-codegen-request-body-name": "payload" } } }, "components": { "schemas": { "CreateAgentRequest": { "required": [ "displayName", "schemas" ], "type": "object", "properties": { "schemas": { "type": "array", "description": "**REQUIRED** - SCIM schema URIs", "example": [ "urn:ietf:params:scim:schemas:core:ibm:2.0:Agent" ], "items": { "type": "string" } }, "displayName": { "maxLength": 256, "type": "string", "description": "**REQUIRED** - Human-readable name for the agent. Must be unique within tenant. Max 256 characters.", "example": "Production API Service" }, "status": { "type": "string", "description": "Agent status (optional). Always set to `UNDER_REVIEW` on creation — any value provided is silently overridden.", "example": "UNDER_REVIEW", "enum": [ "DEFAULT", "ACTIVE", "SUSPENDED", "UNDER_REVIEW" ] }, "description": { "maxLength": 1024, "type": "string", "description": "Detailed description of the agent's purpose (optional). Max 1024 characters.", "example": "API service for production workloads" }, "externalIds": { "maxItems": 1000, "type": "array", "description": "External identifiers from source systems (optional). Each externalId must be unique within the tenant. Max 1000 items, each max 128 chars.", "example": [ "ext-agent-123", "legacy-id-456" ], "items": { "maxLength": 128, "type": "string" } }, "owners": { "type": "array", "description": "Owner user IDs (optional).", "items": { "$ref": "#/components/schemas/Owner" } }, "tags": { "type": "array", "description": "Custom tags for categorization (optional).", "example": [ "production", "api-service" ], "items": { "type": "string" } }, "authMethods": { "type": "array", "description": "Authentication methods (optional). Each requires 'name' (unique within agent, max 128 chars) and 'type'.", "items": { "$ref": "#/components/schemas/AuthMethod" } } }, "description": "Agent creation request schema. Both 'schemas' and 'displayName' are required." }, "AuthMethod": { "required": [ "name", "type" ], "type": "object", "properties": { "name": { "maxLength": 128, "type": "string", "description": "Unique identifier for this authentication method within the agent (max 128 chars)", "example": "primary-jwt-auth" }, "type": { "type": "string", "description": "Type of authentication method", "example": "jwt", "enum": [ "jwt", "certificate", "oidc", "oauth", "apikey", "mtls", "svid-jwt", "svid-x509" ] }, "display": { "type": "string", "description": "Human-readable name", "example": "JWT Authentication" }, "attributes": { "type": "array", "description": "Additional attributes for the authentication method", "example": [ "iss=https://issuer.example.com", "sub=service-account" ], "items": { "type": "string" } } }, "description": "Authentication method configuration" }, "Owner": { "type": "object", "properties": { "value": { "type": "string", "description": "Unique identifier of the owner", "example": "user-123" }, "type": { "type": "string", "description": "Type of owner", "example": "User", "enum": [ "User", "Group", "Role", "Agent" ] }, "$ref": { "type": "string", "description": "URI reference to the owner resource", "example": "/cdprofilemgmt/v2.0/Users/user-123" }, "display": { "type": "string", "description": "Display name of the owner (auto-populated from Cloud Directory)", "example": "John Doe" } }, "description": "Owner reference (User, Group, Role, or Agent)" } } }, "x-original-swagger-version": "2.0", "x-explorer-enabled": false } ```