Onboard FTD device - Security Cloud Control Firewall Manager API Documentation

{"type":"api","title":"Onboard FTD device","meta":{"id":"/apps/pubhub/media/cdo-api-documentation/241e37f202cf9838405f7ca5ed9f7d31d807d7bd/9b0e4c9a-48cb-3530-a00a-1f32fbf2438c","info":{"title":"Cisco Security Cloud Control Firewall Manager API","version":"1.22.0","description":"Use the documentation to explore the endpoints Security Cloud Control Firewall Manager has to offer","contact":{"name":"Cisco Security Cloud Control TAC","email":"cdo.tac@cisco.com"}},"openapi":"3.0.1","servers":[{"url":"https://api.us.security.cisco.com/firewall","description":"US"},{"url":"https://api.eu.security.cisco.com/firewall","description":"EU"},{"url":"https://api.apj.security.cisco.com/firewall","description":"APJ"},{"url":"https://api.au.security.cisco.com/firewall","description":"AUS"},{"url":"https://api.in.security.cisco.com/firewall","description":"IN"},{"url":"https://api.uae.security.cisco.com/firewall","description":"UAE"},{"url":"https://api.int.security.cisco.com/firewall","description":"Staging"},{"url":"https://scale.manage.security.cisco.com/api/rest","description":"Scale"},{"url":"https://ci.manage.security.cisco.com/api/rest","description":"CI"},{"url":"https://devfed.cdo.cisco.com/api/rest","description":"Devfed"},{"url":"https://manage.dev.secure.cisco/api/rest","description":"Devf9"},{"url":"https://manage.stg.secure.cisco/api/rest","description":"Stgf9"},{"url":"https://manage.secure.cisco/api/rest","description":"ProdF9"},{"url":"https://manage.securitydod.cisco/api/rest","description":"IL5"}],"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","scheme":"bearer","type":"http"}}},"spec":{"description":"This is an asynchronous operation to generate a registration key for a cdFMC managed FTD device in the CDO tenant. This operation returns a link to a transaction object that can be used to monitor the progress of the operation. Onboarding a cdFMC managed FTD device is a two-step process: the first step, handled by this operation, creates an FTD device with a configure manager string that must be pasted into the FTD device's Command-Line Interface. The FTD then uses this information to register itself with the Security Cloud Control tenant.","operationId":"createFtdDevice","requestBody":{"content":{"application/json":{"schema":{"properties":{"deviceType":{"description":"Specify the type of the FTD. The only supported type of FTD is CDFMC_MANAGED_FTD.","enum":["CDFMC_MANAGED_FTD"],"type":"string"},"fmcAccessPolicyUid":{"description":"Specify the unique identifier, represented as a UUID, of the FMC access policy to apply to this device. If this field is specified, the 'template' field must remain unspecified. Exactly one of 'fmcAccessPolicyUid' or 'template' must be supplied.","example":"7131daad-e813-4b8f-8f42-be1e241e8cdb","format":"uuid","type":"string"},"ftdHostname":{"description":"The FQDN or public IP of the FTD being registered to the cdFMC. This hostname must be accessible from the public internet, as the cdFMC will use it to initiate the connection to the FTD. Required when useCdFmcTriggeredRegistration is true; must not be specified otherwise.","example":"18.2.25.7","type":"string"},"labels":{"description":"Labels used to identify/tag Security Cloud Control entities.","nullable":true,"properties":{"groupedLabels":{"additionalProperties":{"description":"Groups of labels used to identify/tag Security Cloud Control entities.","example":{"group1":["label-1","label-2"],"group2":["label-1","label-2"]},"items":{"description":"Groups of labels used to identify/tag Security Cloud Control entities.","example":"{\"group1\":[\"label-1\",\"label-2\"],\"group2\":[\"label-1\",\"label-2\"]}","type":"string"},"type":"array","uniqueItems":true},"description":"Groups of labels used to identify/tag Security Cloud Control entities.","example":{"group1":["label-1","label-2"],"group2":["label-1","label-2"]},"type":"object"},"ungroupedLabels":{"description":"Set of free-labels used to identify/tag Security Cloud Control entities.","example":["label-a","label-b","label-c"],"items":{"description":"Set of free-labels used to identify/tag Security Cloud Control entities.","example":"[\"label-a\",\"label-b\",\"label-c\"]","type":"string"},"type":"array","uniqueItems":true}},"type":"object","$$ref":"#/components/schemas/Labels"},"licenses":{"description":"Specify a set of licenses to apply to the device. This field is required for access-policy onboarding. It may be omitted or empty for template onboarding, but it must not contain any licenses when a template is supplied.","example":["BASE","CARRIER"],"items":{"description":"Specify a set of licenses to apply to the device. This field is required for access-policy onboarding. It may be omitted or empty for template onboarding, but it must not contain any licenses when a template is supplied.","enum":["BASE","CARRIER","THREAT","MALWARE","URLFilter"],"example":"[\"BASE\",\"CARRIER\"]","type":"string"},"type":"array","uniqueItems":true},"name":{"description":"Specify a human-readable name for the device.","example":"My FTD","minLength":1,"type":"string"},"natId":{"description":"The NAT ID used during cdFMC-triggered registration, where the cdFMC initiates the connection to the FTD (as opposed to the default flow, where the FTD connects to the cdFMC). Required when useCdFmcTriggeredRegistration is true; must not be specified otherwise.","example":"abc237","type":"string"},"performanceTier":{"description":"Specify the performance tier of the FTDv (required only if isVirtual is set to true).","enum":["FTDv5","FTDv10","FTDv20","FTDv30","FTDv50","FTDv100","FTDv","FTDvU"],"type":"string"},"regKey":{"description":"The registration key used to authenticate the cdFMC-triggered registration, where the cdFMC initiates the connection to the FTD (as opposed to the default flow, where the FTD connects to the cdFMC). Required when useCdFmcTriggeredRegistration is true; must not be specified otherwise.","example":"xyz124","type":"string"},"template":{"description":"Specify the template to apply to this device. If this field is specified, the 'fmcAccessPolicyUid' field must remain unspecified. Exactly one of 'fmcAccessPolicyUid' or 'template' must be supplied.","properties":{"objectOverrides":{"description":"Specify a list of objects to override. All objects that have been marked as overridable in the template must be defined here. Note: Any overrides defined here that are not present in the template configuration will be ignored.","items":{"description":"Specify a list of objects to override. All objects that have been marked as overridable in the template must be defined here. Note: Any overrides defined here that are not present in the template configuration will be ignored.","properties":{"name":{"description":"Specify the name of the object to override.","minLength":1,"type":"string"},"type":{"description":"Specify the type of the object to override. The type should match the type of the object used in the template.","enum":["Network","Host","FQDN","Range"],"example":"Network","type":"string"},"uid":{"description":"Specify the unique identifier, represented as a UUID, of the object to override.","example":"0d0cc559-43a0-449a-84a9-28310ede72ec","format":"uuid","type":"string"},"value":{"description":"Specify the value to override the object with.","minLength":1,"type":"string"}},"required":["name","type","uid","value"],"type":"object","$$ref":"#/components/schemas/FmcObjectOverride"},"type":"array"},"templateVariables":{"description":"Specify the list of template variables configured on the template. All required template variables must be defined here, and should have values valid for the type of the variable. Any invalid input will result in the template not being applied to the device upon onboarding. Note: Any variables defined here that are not present in the template will be ignored.","items":{"description":"Specify the list of template variables configured on the template. All required template variables must be defined here, and should have values valid for the type of the variable. Any invalid input will result in the template not being applied to the device upon onboarding. Note: Any variables defined here that are not present in the template will be ignored.","properties":{"name":{"description":"Specify the name of the object to override.","minLength":1,"type":"string"},"value":{"description":"Specify the value of the template variable. The value specified should be valid for the template variable, as defined in the template configuration.","minLength":1,"type":"string"}},"required":["name","value"],"type":"object","$$ref":"#/components/schemas/FmcTemplateVariable"},"type":"array"},"uid":{"description":"Specify the unique identifier, represented as a UUID, of the template to apply to the onboarded device.","example":"2cadad15-dc8b-4bc4-899f-b9badcfc56a3","format":"uuid","type":"string"}},"required":["uid"],"type":"object","$$ref":"#/components/schemas/FtdOnboardingTemplateConfiguration"},"useCdFmcTriggeredRegistration":{"description":"If your FTD is publicly accessible, then you can choose to use the cdFMC triggered registration flow. If this field is set to true, the ftdHostname, natId, and regKey fields must be specified.","type":"boolean"},"virtual":{"description":"Indicate whether the FTD is a virtual or a physical device.","example":true,"type":"boolean"}},"required":["deviceType","name"],"type":"object","$$ref":"#/components/schemas/FtdCreateOrUpdateInput"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"properties":{"cancellable":{"type":"boolean"},"cdoTransactionStatus":{"description":"Status of the transaction.","enum":["PENDING","IN_PROGRESS","CANCELLED","DONE","ERROR"],"example":"IN_PROGRESS","type":"string"},"entityUid":{"description":"Unique identifier of the entity that the transaction is triggered on. This can be empty, for a transaction that is not tied to an entity, such as transactions which refresh RA VPN sessions.","example":"f5f660d4-4b81-4374-877d-fbc4bee894e2","format":"uuid","type":"string"},"entityUrl":{"description":"URL to access the entity that the transaction is triggered on. This can be empty, for a transaction that is not tied to an entity, such as transactions which refresh RA VPN sessions.","example":"https://edge.us.cdo.cisco.com/platform/public-api/v1/inventory/devices/f5f660d4-4b81-4374-877d-fbc4bee894e2","type":"string"},"errorDetails":{"additionalProperties":{"description":"Transaction error details, if any.","type":"string"},"description":"Transaction error details, if any.","type":"object"},"errorMessage":{"description":"Transaction error message, if any.","type":"string"},"lastUpdatedTime":{"description":"Time (UTC; represented using the RFC-3339 standard) at which the transaction status was last updated.","example":"2023-12-13T08:15:44Z","format":"date-time","type":"string"},"submissionTime":{"description":"Time (UTC; represented using the RFC-3339 standard) at which the transaction was triggered.","example":"2023-12-13T05:15:44Z","format":"date-time","type":"string"},"tenantUid":{"description":"Unique identifier of the tenant that the transaction was triggered on.","example":"5131daad-e813-4b8f-8f42-be1e241e2cdb","format":"uuid","type":"string"},"transactionDetails":{"additionalProperties":{"description":"Transaction details, if any.","type":"string"},"description":"Transaction details, if any.","type":"object"},"transactionPollingUrl":{"description":"Polling URL to track the progress of the transaction.","example":"https://edge.us.cdo.cisco.com/platform/v1/transactions/7131daad-e813-4b8f-8f42-be1e241e8cdb","type":"string"},"transactionType":{"description":"Type of the transaction.","enum":["ONBOARD_ASA","ONBOARD_IOS","ONBOARD_DUO_ADMIN_PANEL","CREATE_FTD","ONBOARD_FTD_ZTP","REGISTER_FTD","DELETE_CDFMC_MANAGED_FTD","RECONNECT_ASA","READ_ASA","BULK_READ_ASA","EXECUTE_CLI_COMMAND","BULK_ACCEPT_ASA_CERTIFICATES","DEPLOY_ASA_DEVICE_CHANGES","DEPLOY_FTD_DEVICE_CHANGES","INDEX_TENANT","TERMINATE_DEVICE_RA_VPN_SESSIONS","REFRESH_RA_VPN_SESSIONS","TERMINATE_USER_RA_VPN_SESSIONS","UPGRADE_ASA","UPGRADE_FTD","UPGRADE_FTD_CACHE","UPGRADE_SECURE_CLIENT_PACKAGES","MSP_UPGRADE_ASAS","MSP_UPGRADE_FTDS","MSP_UPGRADE_SECURE_CLIENT_PACKAGES","MSP_GET_COMPATIBLE_FTD_UPGRADE_PACKAGES","MSP_GET_COMPATIBLE_SECURE_CLIENT_UPGRADE_PACKAGES","CREATE_SDC","SEND_AI_ASSISTANT_MESSAGE","MSP_CREATE_TENANT","MSP_REVOKE_TENANT_MSP_PORTAL_RELATIONSHIP","MSP_ADD_USERS_TO_TENANT","MSP_ADD_USER_GROUPS_TO_TENANT","MSP_DELETE_USERS_FROM_TENANT","MSP_DELETE_USER_GROUPS_FROM_TENANT","MSP_ADD_EXISTING_TENANT","MSP_ENABLE_MULTICLOUD_DEFENSE","MSP_PROVISION_CDFMC","MSP_UPDATE_TENANT_SETTINGS","CREATE_USERS","DELETE_USERS","EXECUTE_ASA_COMMAND","ANALYZE_POLICIES","TRIGGER_FMC_DATA_EXPORT","STAGE_POLICIES","SYNC_ACCESS_POLICIES","SYNC_POLICIES","EXPORT_DEVICES","EXPORT_CLOUD_SERVICES","EXPORT_MANAGERS","EXPORT_TEMPLATES","EXPORT_DEVICE_LICENSES","EXPORT_TENANT_LICENSES","EXPORT_TENANTS","PROVISION_SDWAN_SAL_RESOURCES","DEPROVISION_SDWAN_SAL_RESOURCES","PROVISION_FIREWALL_SAL_RESOURCES","DEPROVISION_FIREWALL_SAL_RESOURCES","RENEW_SAL_LICENSE","PAID_SAL_LICENSE","EXPIRE_SAL_LICENSE","REMOVE_SSX_SAL_SUBSCRIPTION","ASA_HEALTH_METRICS_TENANT_PROVISIONING","UPDATE_DEVICE_BULK","AGENTIC_JOB","IMPORT_FMC_OBJECTS","NAT_PAO_TRIGGER_PDF_GENERATION","NAT_PAO_APPLY_REMEDIATION","BIDIRECTIONAL_OBJECT_RECONCILIATION","CALCULATE_FTD_PENDING_CHANGES","CALCULATE_ASA_CONFIG_COMMANDS"],"example":"ONBOARD_ASA","type":"string"},"transactionUid":{"description":"Unique identifier of the transaction triggered.","example":"7131daad-e813-4b8f-8f42-be1e241e8cdb","format":"uuid","type":"string"}},"type":"object","$$ref":"#/components/schemas/CdoTransaction"}}},"description":"Security Cloud Control Transaction object that can be used to track the progress of the creation operation."},"400":{"content":{"application/json":{"schema":{"properties":{"details":{"additionalProperties":{"description":"Additional details, if any, about the error.","example":{},"type":"object"},"description":"Additional details, if any, about the error.","example":{},"type":"object"},"errorCode":{"description":"Unique code that describes the error.","enum":["INVALID_INPUT","UNAUTHORIZED","FORBIDDEN","NOT_FOUND","METHOD_NOT_ALLOWED","CONFLICT","TOO_MANY_REQUESTS","SERVER_ERROR","PROXY_ERROR","BAD_REQUEST","UNPROCESSABLE_ENTITY"],"example":"INVALID_INPUT","type":"string"},"errorMsg":{"description":"Human-readable error description in English.","example":"sample error","type":"string"}},"type":"object","$$ref":"#/components/schemas/CommonApiError"}}},"description":"Invalid input provided. Check the response for details.","$$ref":"#/components/responses/http400BadRequest"},"401":{"content":{"application/json":{"schema":{"properties":{"error":{"description":"A human-readable error description in English.","example":"invalid_token","type":"string"},"errorDescription":{"description":"A human-readable error description in English.","example":"Your token is invalid","type":"string"}},"type":"object","$$ref":"#/components/schemas/AuthenticationError"}}},"description":"Request not authorized.","$$ref":"#/components/responses/http401Unauthorised"},"403":{"content":{"application/json":{"schema":{"properties":{"details":{"additionalProperties":{"description":"Additional details, if any, about the error.","example":{},"type":"object"},"description":"Additional details, if any, about the error.","example":{},"type":"object"},"errorCode":{"description":"Unique code that describes the error.","enum":["INVALID_INPUT","UNAUTHORIZED","FORBIDDEN","NOT_FOUND","METHOD_NOT_ALLOWED","CONFLICT","TOO_MANY_REQUESTS","SERVER_ERROR","PROXY_ERROR","BAD_REQUEST","UNPROCESSABLE_ENTITY"],"example":"INVALID_INPUT","type":"string"},"errorMsg":{"description":"Human-readable error description in English.","example":"sample error","type":"string"}},"type":"object","$$ref":"#/components/schemas/CommonApiError"}}},"description":"User does not have sufficient privileges to perform this operation.","$$ref":"#/components/responses/http403Forbidden"},"500":{"content":{"application/json":{"schema":{"properties":{"details":{"additionalProperties":{"description":"Additional details, if any, about the error.","example":{},"type":"object"},"description":"Additional details, if any, about the error.","example":{},"type":"object"},"errorCode":{"description":"Unique code that describes the error.","enum":["INVALID_INPUT","UNAUTHORIZED","FORBIDDEN","NOT_FOUND","METHOD_NOT_ALLOWED","CONFLICT","TOO_MANY_REQUESTS","SERVER_ERROR","PROXY_ERROR","BAD_REQUEST","UNPROCESSABLE_ENTITY"],"example":"INVALID_INPUT","type":"string"},"errorMsg":{"description":"Human-readable error description in English.","example":"sample error","type":"string"}},"type":"object","$$ref":"#/components/schemas/CommonApiError"}}},"description":"Internal server error."}},"security":[{"bearerAuth":[]}],"summary":"Onboard FTD device","tags":["Inventory"],"__originalOperationId":"createFtdDevice","method":"post","path":"/v1/inventory/devices/ftds"}}