{"type":"api","title":"Create Integration","meta":{"id":"/apps/pubhub/media/cloud-security-apis-in-eft/a8abec13eed189c2473088a77eb959c04c5057b8/ac5e908c-3245-3ba5-9e49-5ab5d54d743e","info":{"title":"Cisco Secure Access Third-Party Integrations API","version":"1.0.1","description":"Create and manage the third-party applications integrated with Secure Access.\nSecure Access integrates with third-party applications, which support either REST APIs or Webhooks.","contact":{"name":"Cloud Security Developer Community"}},"security":[{"oauthFlow":[]}],"tags":[{"name":"Integrations","description":"Integration management"},{"name":"Credentials","description":"Credential management"},{"name":"Integration Types","description":"Integration types"},{"name":"Secure Access"}],"x-parser-conf":{"overview":{"markdownPath":"secure-access/reference/admin/third-party-integrations-overview.md","uri":"secure-access-api-reference-third-party-integrations-overview"}},"openapi":"3.0.3","servers":[{"url":"https://api.sse.cisco.com/{basePath}","variables":{"basePath":{"default":"admin/v2"}}}],"securitySchemes":{"oauthFlow":{"type":"oauth2","description":"The client credential flow.","flows":{"clientCredentials":{"tokenUrl":"https://api.sse.cisco.com/auth/v2/token","scopes":{"admin.integrations.thirdparty:read":"Read third-party integrations","admin.integrations.thirdparty:write":"Create, update, delete third-party integrations"}}}}}},"spec":{"summary":"Create Integration","operationId":"createIntegration","description":"Create a third-party integration in the organization.","security":[{"oauthFlow":["admin.integrations.thirdparty:write"]}],"tags":["Integrations","Secure Access"],"requestBody":{"content":{"application/json":{"schema":{"properties":{"config":{"description":"The configuration settings for the third-party integration.","type":"object","properties":{"edge":{"description":"The configuration settings used to create the Microsoft Edge for Business integration.","properties":{"applicationClientId":{"description":"Edge application (client) ID","example":"00001111-aaaa-2222-bbbb-3333cccc4444","type":"string"},"resourceAppId":{"description":"Edge resource application ID","example":"11112222-bbbb-3333-cccc-4444dddd5555","type":"string"},"secret":{"description":"Edge client secret","example":"7a9b0c1d-e2f3-g4h5-i6j7-k8l9m0n1o2p3","type":"string"},"tenantId":{"description":"Edge tenant ID","example":"72f988bf-86f1-41af-91ab-2d7cd011db47","type":"string"}},"required":["tenantId","applicationClientId","secret","resourceAppId"],"type":"object","$$ref":"#/components/schemas/EdgeConfigInput"},"intune":{"type":"object","description":"The configuration settings used to create or update the Azure AD application.","properties":{"clientCredentialId":{"description":"The Azure AD client ID.","type":"string","example":"credentialid1","$$ref":"#/components/schemas/clientCredentialIdIntune"},"clientCredentialSecret":{"description":"The Azure AD client secret.","type":"string","example":"credentialsecret1","$$ref":"#/components/schemas/clientCredentialSecretIntune"},"clientCredentialTokenUrl":{"description":"The OAuth 2.0 token endpoint URL for the authentication of the Azure AD application.","type":"string","example":"tokenauthurl@abc.com","$$ref":"#/components/schemas/clientCredentialTokenUrlIntune"}},"example":{"clientCredentialId":"intune-client-123","clientCredentialSecret":"secret-value","clientCredentialTokenUrl":"https://login.microsoftonline.com/tenant/oauth2/v2.0/token"},"$$ref":"#/components/schemas/IntuneConfigInput"},"jamf":{"type":"object","description":"The configuration settings used to create or update the Jamf Pro integration.","properties":{"clientCredentialId":{"description":"The Jamf Pro client ID.","type":"string","example":"credentialid1","$$ref":"#/components/schemas/clientCredentialIdJamf"},"clientCredentialSecret":{"description":"The Jamf Pro client secret.","type":"string","example":"credentialsecret1","$$ref":"#/components/schemas/clientCredentialSecretJamf"},"url":{"description":"The base URL of the integration.","type":"string","example":"https://company.jamfcloud.com","$$ref":"#/components/schemas/url"}},"example":{"clientCredentialId":"jamf-client-789","clientCredentialSecret":"jamf-secret","url":"https://company.jamfcloud.com"},"$$ref":"#/components/schemas/JamfConfigInput"},"securityEvents":{"required":["sources","targets"],"type":"object","description":"The configuration settings used to create the push security events third-party integration.","additionalProperties":false,"properties":{"connections":{"description":"The list of webhook connections. Each connection defines a webhook and delivery format.","items":{"type":"object","required":["targetId","format"],"properties":{"format":{"description":"The label that describes the format of the outbound security event.","enum":["secureaccess.events.security.splunk-hec.v1","secureaccess.events.security.cloudevents.v1"],"example":"secureaccess.events.security.cloudevents.v1","type":"string","$$ref":"#/components/schemas/format"},"targetId":{"description":"The ID of the Webhook.v1 integration that receives the security events.","example":"webhook.v1:abc123","type":"string","$$ref":"#/components/schemas/targetId"}},"example":{"format":"secureaccess.events.security.cloudevents.v1","targetId":"webhook.v1:abc123"},"$$ref":"#/components/schemas/SecurityEventsConnectionInput"},"type":"array","nullable":true},"sources":{"type":"array","nullable":true,"items":{"type":"string","description":"The label for the event source."},"description":"The list of event sources that the system will monitor. Use `all` to monitor all available event sources.","example":["dns","web","ravpn","firewall"]},"targets":{"type":"array","nullable":true,"items":{"type":"string","description":"The unique identifier for the webhook.v1 integration."},"description":"The list of unique identifiers for the webhook.v1 integrations.\nThese webhook.v1 integrations will receive the security events from Secure Access.\n**Note:** The list must contain at least one ID for a webhook.v1 integration.","example":["webhook.v1:abc123","webhook.v1:def456"]}},"$$ref":"#/components/schemas/SecurityEventsConfigInput"},"webhook":{"type":"object","description":"The configuration settings used to create or update the Webhook integration.","properties":{"headers":{"additionalProperties":{"type":"string","description":"The HTTP headers for the Webhook integration."},"type":"object","$$ref":"#/components/schemas/headers"},"queryParams":{"type":"object","description":"The query parameters for the Webhook integration.","additionalProperties":{"type":"string"},"$$ref":"#/components/schemas/queryParams"},"url":{"description":"The URL of the Webhook integration for receiving notifications.","type":"string","example":"https://api.company.com/webhook/integration-events","$$ref":"#/components/schemas/urlWebHook"}},"example":{"url":"https://api.company.com/webhook","headers":{"Content-Type":"application/json"},"queryParams":{"source":"integration-service"}},"$$ref":"#/components/schemas/WebhookConfigInput"}}},"intuneConfig":{"type":"object","description":"The configuration settings used to create or update the Azure AD application.","properties":{"clientCredentialId":{"description":"The Azure AD client ID.","type":"string","example":"credentialid1","$$ref":"#/components/schemas/clientCredentialIdIntune"},"clientCredentialSecret":{"description":"The Azure AD client secret.","type":"string","example":"credentialsecret1","$$ref":"#/components/schemas/clientCredentialSecretIntune"},"clientCredentialTokenUrl":{"description":"The OAuth 2.0 token endpoint URL for the authentication of the Azure AD application.","type":"string","example":"tokenauthurl@abc.com","$$ref":"#/components/schemas/clientCredentialTokenUrlIntune"}},"example":{"clientCredentialId":"intune-client-123","clientCredentialSecret":"secret-value","clientCredentialTokenUrl":"https://login.microsoftonline.com/tenant/oauth2/v2.0/token"},"$$ref":"#/components/schemas/IntuneConfigInput"},"jamfConfig":{"type":"object","description":"The configuration settings used to create or update the Jamf Pro integration.","properties":{"clientCredentialId":{"description":"The Jamf Pro client ID.","type":"string","example":"credentialid1","$$ref":"#/components/schemas/clientCredentialIdJamf"},"clientCredentialSecret":{"description":"The Jamf Pro client secret.","type":"string","example":"credentialsecret1","$$ref":"#/components/schemas/clientCredentialSecretJamf"},"url":{"description":"The base URL of the integration.","type":"string","example":"https://company.jamfcloud.com","$$ref":"#/components/schemas/url"}},"example":{"clientCredentialId":"jamf-client-789","clientCredentialSecret":"jamf-secret","url":"https://company.jamfcloud.com"},"$$ref":"#/components/schemas/JamfConfigInput"},"name":{"description":"The name of the integration.","maxLength":250,"minLength":1,"type":"string","example":"integration one","$$ref":"#/components/schemas/integrationName"},"securityEventsConfig":{"required":["sources","targets"],"type":"object","description":"The configuration settings used to create the push security events third-party integration.","additionalProperties":false,"properties":{"connections":{"description":"The list of webhook connections. Each connection defines a webhook and delivery format.","items":{"type":"object","required":["targetId","format"],"properties":{"format":{"description":"The label that describes the format of the outbound security event.","enum":["secureaccess.events.security.splunk-hec.v1","secureaccess.events.security.cloudevents.v1"],"example":"secureaccess.events.security.cloudevents.v1","type":"string","$$ref":"#/components/schemas/format"},"targetId":{"description":"The ID of the Webhook.v1 integration that receives the security events.","example":"webhook.v1:abc123","type":"string","$$ref":"#/components/schemas/targetId"}},"example":{"format":"secureaccess.events.security.cloudevents.v1","targetId":"webhook.v1:abc123"},"$$ref":"#/components/schemas/SecurityEventsConnectionInput"},"type":"array","nullable":true},"sources":{"type":"array","nullable":true,"items":{"type":"string","description":"The label for the event source."},"description":"The list of event sources that the system will monitor. Use `all` to monitor all available event sources.","example":["dns","web","ravpn","firewall"]},"targets":{"type":"array","nullable":true,"items":{"type":"string","description":"The unique identifier for the webhook.v1 integration."},"description":"The list of unique identifiers for the webhook.v1 integrations.\nThese webhook.v1 integrations will receive the security events from Secure Access.\n**Note:** The list must contain at least one ID for a webhook.v1 integration.","example":["webhook.v1:abc123","webhook.v1:def456"]}},"$$ref":"#/components/schemas/SecurityEventsConfigInput"},"tags":{"type":"array","description":"The list of tags associated with the integration.","items":{"type":"string","description":"The tag associated with the integration."},"example":["integration one"],"$$ref":"#/components/schemas/integrationTags"},"type":{"description":"Type of integration to create","enum":["chrome-enterprise.v1","edge-business.v1","webhook.v1","jamf.v1","intune.v1","security-events.v1"],"type":"string"},"webhookConfig":{"type":"object","description":"The configuration settings used to create or update the Webhook integration.","properties":{"headers":{"additionalProperties":{"type":"string","description":"The HTTP headers for the Webhook integration."},"type":"object","$$ref":"#/components/schemas/headers"},"queryParams":{"type":"object","description":"The query parameters for the Webhook integration.","additionalProperties":{"type":"string"},"$$ref":"#/components/schemas/queryParams"},"url":{"description":"The URL of the Webhook integration for receiving notifications.","type":"string","example":"https://api.company.com/webhook/integration-events","$$ref":"#/components/schemas/urlWebHook"}},"example":{"url":"https://api.company.com/webhook","headers":{"Content-Type":"application/json"},"queryParams":{"source":"integration-service"}},"$$ref":"#/components/schemas/WebhookConfigInput"}},"required":["name","type"],"type":"object","$$ref":"#/components/schemas/CreateIntegrationBody"}}},"required":true},"responses":{"201":{"headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The date and time (ISO 8601-formatted timestamp) when the system returned the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"},"Location":{"description":"The URL of the created integration.","schema":{"type":"string","example":"https://api.sse.cisco.com/admin/v2/integrations/12345"}}},"content":{"application/json":{"schema":{"type":"object","description":"The link and ID of the created integration.","required":["href","id"],"properties":{"href":{"description":"The URL for the integration.","type":"string","example":"https://api.sse.cisco.com/admin/v2/integrations/123","$$ref":"#/components/schemas/integrationHref"},"id":{"description":"The unique identifier of the integration.","type":"string","example":"134456a","$$ref":"#/components/schemas/integrationId"}},"example":{"href":"https://api.sse.cisco.com/admin/v2/integrations/12345a","id":"12345a"},"$$ref":"#/components/schemas/CreateOutputBody"}}},"description":"Created"},"400":{"description":"Bad Request","headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The date and time (ISO 8601-formatted timestamp) when the system returned the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"detail":{"description":"A human-readable explanation specific to this occurrence of the problem.","example":"Property foo is required but is missing.","type":"string"},"errors":{"description":"Optional list of individual error details","items":{"additionalProperties":false,"properties":{"location":{"description":"Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'","type":"string"},"message":{"description":"Error message text","type":"string"},"value":{"description":"The value at the given location"}},"type":"object","$$ref":"#/components/schemas/ErrorDetail"},"type":"array","nullable":true},"instance":{"description":"A URI reference that identifies the specific occurrence of the problem.","example":"https://example.com/error-log/abc123","format":"uri","type":"string"},"status":{"description":"The HTTP status code.","example":400,"format":"int64","type":"integer"},"title":{"description":"A short, human-readable summary of the problem type. This value should not change between occurrences of the error.","example":"Bad Request","type":"string"},"type":{"default":"about:blank","description":"A URI reference to human-readable documentation for the error.","example":"https://example.com/errors/example","format":"uri","type":"string"}},"type":"object","$$ref":"#/components/schemas/ErrorModel"}}},"$$ref":"#/components/responses/400Error"},"401":{"description":"Unauthorized","headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The date and time (ISO 8601-formatted timestamp) when the system returned the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Unauthorized","example":"Authorization token is invalid."},"status":{"type":"integer","description":"The HTTP status code returned in the response.","example":401}}}}},"$$ref":"#/components/responses/401Error"},"403":{"description":"Forbidden","headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The date and time (ISO 8601-formatted timestamp) when the system returned the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message explaining the reason for failure.","example":"Forbidden"},"status":{"type":"integer","description":"The HTTP status code returned in the response.","example":403}}}}},"$$ref":"#/components/responses/403Error"},"404":{"description":"Not Found","headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The date and time (ISO 8601-formatted timestamp) when the system returned the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message explaining the reason for failure.","example":"Not Found"},"status":{"type":"integer","description":"The HTTP status code returned in the response.","example":404}}}}},"$$ref":"#/components/responses/404Error"},"500":{"description":"Internal Server Error","headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The date and time (ISO 8601-formatted timestamp) when the system returned the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"detail":{"description":"A human-readable explanation specific to this occurrence of the problem.","example":"Property foo is required but is missing.","type":"string"},"errors":{"description":"Optional list of individual error details","items":{"additionalProperties":false,"properties":{"location":{"description":"Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'","type":"string"},"message":{"description":"Error message text","type":"string"},"value":{"description":"The value at the given location"}},"type":"object","$$ref":"#/components/schemas/ErrorDetail"},"type":"array","nullable":true},"instance":{"description":"A URI reference that identifies the specific occurrence of the problem.","example":"https://example.com/error-log/abc123","format":"uri","type":"string"},"status":{"description":"The HTTP status code.","example":400,"format":"int64","type":"integer"},"title":{"description":"A short, human-readable summary of the problem type. This value should not change between occurrences of the error.","example":"Bad Request","type":"string"},"type":{"default":"about:blank","description":"A URI reference to human-readable documentation for the error.","example":"https://example.com/errors/example","format":"uri","type":"string"}},"type":"object","$$ref":"#/components/schemas/ErrorModel"}}},"$$ref":"#/components/responses/500Error"}},"__originalOperationId":"createIntegration","method":"post","path":"/integrations"}}