Cisco Secure Firewall Management Relationships API

openapi: 3.2.0
info:
  description: MSP APIs for viewing, creating and updating the manager and managed organizations
  title: MSP Management Relationships API
  version: 1.4.0
  x-provenance:
    method: harvested
    authored_by: Cisco Security Cloud Control
    harvested_by: API Evangelist
    harvested_on: '2026-08-19'
    first_party: true
    note: Published by Cisco. Retrieved unmodified except for this x-provenance block.
    provider_published: true
  x-evidence:
  - type: source
    url: https://github.com/CiscoDevNet/scc-public-api-docs/blob/main/specs/msp.yaml
  - type: raw
    url: https://raw.githubusercontent.com/CiscoDevNet/scc-public-api-docs/main/specs/msp.yaml
servers:
- url: https://api.int.security.cisco.com/identity
  variables:
    baseUrl:
      default: https://api.int.security.cisco.com/identity
    domain:
      default: https://sso-apps-preview.myverysecuresignon.name/api
security:
- OpenID: []
- bearerAuth: []
tags:
- name: Management Relationships
paths:
  /enterprises/{id}/addManaged:
    post:
      description: Establishes management relationships between the specified manager organization and one or more existing organizations. All organizations must exist before creating relationships.
      operationId: addEnterpriseManagementRelationship
      parameters:
      - description: manager enterprise id. This API works only for the manager enterprise
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitlementShareRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  managedOrgs:
                    items:
                      $ref: '#/components/schemas/PostManagedRelationshipResponse'
                    type: array
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - User is not an admin of the associated enterprise
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - User is not an admin of the associated enterprise
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      security:
      - bearerAuth: []
      summary: Add management relationships to existing organizations
      tags:
      - Management Relationships
      x-publicly-available: true
  /enterprises/{id}/createManaged:
    post:
      description: Creates a new organization and establishes it as managed by the specified manager organization. This forms a management relationship between the two organizations.
      operationId: createEnterpriseManagementRelationship
      parameters:
      - description: manager enterprise id. This API works only for the manager enterprise
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                country:
                  properties:
                    label:
                      type: string
                    value:
                      type: string
                  type: object
                displayName:
                  type: string
                name:
                  type: string
                region:
                  properties:
                    label:
                      type: string
                    value:
                      type: string
                  type: object
              required:
              - name
              - displayName
              - region
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  managedOrgs:
                    items:
                      $ref: '#/components/schemas/PostManagedRelationshipResponse'
                    type: array
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - User is not an admin of the associated enterprise
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - User is not an admin of the associated enterprise
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      security:
      - bearerAuth: []
      summary: Create a new managed organization
      tags:
      - Management Relationships
      x-publicly-available: true
  /enterprises/{id}/managed:
    get:
      operationId: getEnterpriseManagementRelationshipManaged
      parameters:
      - content:
          application/json:
            schema:
              type: string
        description: ID of the manager org or the managed org
        in: path
        name: id
        required: true
      - content:
          application/json:
            schema:
              type: string
        description: offset to paginated results
        in: query
        name: page
        required: false
      - content:
          application/json:
            schema:
              type: string
        description: to limit the management relationship array response
        in: query
        name: limit
        required: false
      - content:
          application/json:
            schema:
              type: string
        description: 'filter or search on fields such as organizations or subscriptions.

          For example, `filter="oyo"` will return all organizations where Enterprise name like "Toyota", as well as subscription IDs like "subs_oyo123" and product names like  "prod_oyo123".

          '
        in: query
        name: filter
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  limit:
                    example: 10
                    type: integer
                  organizations:
                    items:
                      $ref: '#/components/schemas/organizationsRelationship'
                    type: array
                  page:
                    example: 1
                    type: integer
                  relationshipType:
                    example: managed
                    type: string
                  totalItems:
                    example: 100
                    type: integer
          description: ok
        '404':
          $ref: '#/components/responses/NotFoundError'
        default:
          $ref: '#/components/responses/GeneralError'
      security:
      - bearerAuth: []
      summary: Get all management relationship for the manager organization
      tags:
      - Management Relationships
      x-publicly-available: true
  /enterprises/{id}/manager:
    get:
      operationId: getEnterpriseManagementRelationshipManager
      parameters:
      - content:
          application/json:
            schema:
              type: string
        description: ID of the manager org or the managed org
        in: path
        name: id
        required: true
      - content:
          application/json:
            schema:
              type: string
        description: offset to paginated results
        in: query
        name: page
        required: false
      - content:
          application/json:
            schema:
              type: string
        description: to limit the management relationship array response
        in: query
        name: limit
        required: false
      - content:
          application/json:
            schema:
              type: string
        description: 'filter or search on fields such as organizations or subscriptions.

          For example, `filter="cdk"` will return all organizations where Enterprise name like "cdkLimited", as well as subscription IDs like "subs_cdk123" and product names like  "prod_cdk123".

          '
        in: query
        name: filter
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  limit:
                    example: 10
                    type: integer
                  organizations:
                    items:
                      $ref: '#/components/schemas/organizationsRelationship'
                    type: array
                  page:
                    example: 1
                    type: integer
                  relationshipType:
                    example: manager
                    type: string
                  totalItems:
                    example: 100
                    type: integer
          description: ok
        '404':
          $ref: '#/components/responses/NotFoundError'
        default:
          $ref: '#/components/responses/GeneralError'
      security:
      - bearerAuth: []
      summary: Get all management relationships of managed organization
      tags:
      - Management Relationships
      x-publicly-available: true
  /enterprises/{managedId}/manager/{managerId}:
    get:
      operationId: getEnterpriseManagementRelationshipManagerDetails
      parameters:
      - description: ID of the manager org
        in: path
        name: managerId
        required: true
        schema:
          type: string
      - description: ID of the managed org
        in: path
        name: managedId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  organizations:
                    items:
                      $ref: '#/components/schemas/organizationsRelationship'
                    type: array
                  relationshipType:
                    example: manager
                    type: string
          description: ok
        '404':
          $ref: '#/components/responses/NotFoundError'
        default:
          $ref: '#/components/responses/GeneralError'
      security:
      - bearerAuth: []
      summary: get management relationship details of an associated org
      tags:
      - Management Relationships
      x-publicly-available: true
components:
  schemas:
    EntitlementShareRequest:
      properties:
        managed_orgs:
          example:
          - id: 2b63ff9f-02e2-4f8e-ac98-b9e42c9feae1
            subscriptions:
            - id: subs20250110
              skus:
              - key: BPT-SEC
                quantity: 200
              - key: XDR-ESS
                quantity: 200
            - id: subs20250111
              skus: []
          - id: 3c74e892-f39d-47e6-8299-5759d941c053
            subscriptions:
            - id: subs20250110
              skus:
              - key: BPT-SEC
                quantity: 200
              - key: XDR-ESS
                quantity: 100
            - id: subs20250113
              skus:
              - key: UPT-SEC-ESS
                quantity: 200
          items:
            $ref: '#/components/schemas/EntitlementManagedOrg'
          type: array
      type: object
    AssignedGroups:
      properties:
        id:
          description: id of the group
          example: 6280494d-dd0f-4655-b558-d36ce9a10655
          type: string
        name:
          description: name of the assigned group
          example: Group A
          type: string
    Error:
      properties:
        code:
          format: int32
          type: integer
        message:
          type: string
      required:
      - code
      - message
      type: object
    PostManagedRelationshipResponse:
      properties:
        id:
          description: id of the org
          example: 2b63ff9f-02e2-4f8e-ac98-b9e42c9feae1
          type: string
        name:
          description: name of the org
          example: Test Enterprise
          type: string
        subscriptions:
          items:
            $ref: '#/components/schemas/AssignedSubscriptions'
          type: array
    AssignedSubscriptions:
      properties:
        id:
          description: id of the subscription
          example: subs20251011
          type: string
        skus:
          items:
            properties:
              key:
                example: XDR-ESS
                type: string
              productsInfo:
                description: products on the subscription
                items:
                  properties:
                    assignedEntitlements:
                      description: entitlement quantity shared with the managed org
                      example: 200
                      type: integer
                    product:
                      example: Secure Access
                      type: string
                    productRegion:
                      example: US WEST 2
                      type: string
                  type: object
                type: array
            type: object
          type: array
    EntitlementManagedOrg:
      example:
        id: 2b63ff9f-02e2-4f8e-ac98-b9e42c9feae1
        subscriptions:
        - id: subs20250110
          skus:
          - key: BPT-SEC
            quantity: 200
          - key: XDR-ESS
            quantity: 100
        - id: subs20250111
          skus:
          - key: UPT-SEC-ESS
            quantity: 200
      properties:
        id:
          description: id of the managed org
          example: 2b63ff9f-02e2-4f8e-ac98-b9e42c9feae1
          type: string
        subscriptions:
          items:
            $ref: '#/components/schemas/EntitlementSubscription'
          type: array
      required:
      - id
    EntitlementSubscription:
      properties:
        id:
          description: subscription id
          example: subs20250110
          type: string
        skus:
          items:
            properties:
              key:
                example: XDR-ESS
                type: string
              quantity:
                example: 200
                type: integer
            type: object
          type: array
      type: object
    organizationsRelationship:
      properties:
        assigned_admins:
          items:
            $ref: '#/components/schemas/AssignedAdmins'
          type: array
        assigned_groups:
          example:
          - id: 6280494d-dd0f-4655-b558-d36ce9a10655
            name: Group A
          items:
            $ref: '#/components/schemas/AssignedGroups'
          type: array
        id:
          description: id of the org
          example: 2b63ff9f-02e2-4f8e-ac98-b9e42c9feae1
          type: string
        name:
          description: name of the org
          example: Test Enterprise
          type: string
        region:
          properties:
            label:
              example: North America
              type: string
            value:
              example: NAM
              type: string
          type: object
        subscriptions:
          example:
          - id: subs20251011
            skus:
            - key: BPT-SEC-ESS
              productInfo:
              - assignedEntitlements: 200
                product: Cisco XDR
                productRegion: US-WEST-2
              - assignedEntitlements: 200
                product: Cisco Secure Endpoint
                productRegion: GLOBAL
              - assignedEntitlements: 200
                product: Cisco Secure Email Threat Defense
                productRegion: GLOBAL
          items:
            $ref: '#/components/schemas/AssignedSubscriptions'
          type: array
    AssignedAdmins:
      properties:
        email:
          description: email of the assigned admin
          example: john.doe@xyz.com
          type: string
        id:
          description: id of the admin
          example: 00u251alpxbbASGcC0h8
          type: string
        name:
          description: name of the assigned admin
          example: John Doe
          type: string
  responses:
    NotFoundError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Not Found
      headers:
        Date:
          $ref: '#/components/headers/Date'
    GeneralError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: An unknown error occurred
      headers:
        Date:
          $ref: '#/components/headers/Date'
  headers:
    Date:
      schema:
        pattern: ^.*$
        type: string
  securitySchemes:
    OpenID:
      openIdConnectUrl: https://auth.example.com/.well-known/openid-configuration
      type: openIdConnect
    bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
    piamServiceTokenSecurity:
      flows:
        clientCredentials:
          scopes:
            security:attack-surface-mgmt:identity:mappings-migrate: Grants write and read access to Attack Surface Management product mappings migration APIs
            security:cdo:identity:mappings-migrate: Grants write and read access to CDO product mappings migration APIs
            security:cdo:public-api: Grants write and read access to CDO Public Group Directory APIs
            security:duo:identity:mappings-migrate: Grants write and read access to product mappings migration APIs for Duo Security
            security:etd:identity:mappings-migrate: Grants write and read access to Encrypted Traffic Analytics product mappings migration APIs
            security:global:provisioning-config:write: Global provisioning configuration management
            security:global:provisioning-subscription:write: Global subscription provisioning operations
            security:panoptica:identity:mappings-migrate: Grants write and read access to Panoptica product mappings migration APIs
            security:provisioning:global-config:write: Global configuration write access
            security:provisioning:maintainance:write: Maintenance operations (provisioning, migrations)
            security:provisioning:subscriptions:read: Read subscription data
            security:provisioning:subscriptions:write: Write subscription data
            security:secure-access:identity:mappings-migrate: Grants write and read access to Secure Access product mappings migration APIs
            security:secure-endpoint:identity:mappings-migrate: Grants write and read access to Secure Endpoint product mappings migration APIs
            security:secure-workload:identity:mappings-migrate: Grants write and read access to Secure Workload product mappings migration APIs
            security:subscription:move: Move subscriptions between enterprises
            security:vuln-mgmt:identity:mappings-migrate: Grants write and read access to Vulnerability Management product mappings migration APIs
            security:xdr:identity:mappings-migrate: Grants write and read access to XDR product mappings migration APIs
          tokenUrl: https://auth.example.com/oauth/token
      type: oauth2