Skip to main content

Federating Partners Using API

This article provides information on Zscaler Private Access (ZPA) Business-to-Business (B2B) Partner Federation use cases using APIs. All APIs are rate limited. To learn more, see ZPA API Rate Limits and Understanding Business-to-Business (B2B) Federation.

Generating a Token for a Partner Federation Request

To generate a token for a B2B partner:

  1. Send a POST request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/tenant-federation/token?microtenantId={microtenantId}.

  2. Provide the following in the request endpoint:

    • customerId: The ZPA tenant ID of the customer.
    • microtenantId: The unique identifier of the Microtenant. If you are within a Microtenant, you must pass the microtenantId field when making an API call to retrieve data from that Microtenant. The microtenantId can be obtained from the API Keys page, or can be obtained programmatically using the ZPA cloud service API. Access to certain operations is limited when you are within a Microtenant. If you are within the Default Microtenant, pass microtenantId as 0 when making requests to retrieve data from the Default Microtenant. If the microtenantId is not passed in the request when creating or updating a resource, then the resource is created or updated in the Default Microtenant. To learn more, see Configuring Microtenants Using API.

    For example: /mgmtconfig/v1/customers/72057595111669760/tenant-federation/token?microtenantId=145260601092866314.

  3. Include the request headers to provide information about the request context:

    • Content-Type: application/json
    • Authorization: Bearer <access_token>

  4. Provide the following JSON payload and include expiryTimeInSeconds, the time range in seconds that the access token is valid.

Minimum Criteria JSON Payload​

{
  "expiryTimeInSeconds": 0,
  "notes": "string"
}

Example Minimum Criteria JSON Payload​

{
  "expiryTimeInSeconds": 86400,
  "notes": "Federation request from Acme Corp to share PRA apps."
}

Example Response​

{
  "id": "145260601092866811",
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJjdXN0b21lcklkIjoxNDUyNjA2MDEwOTI4NjY...",
  "tokenExpirationEpochSeconds": 1745265432
}

A successful response returns code 200. To learn more, see ZPA API Codes.

Verifying a Token for a Partner Federation Request

A business partner (host or guest) can verify a token and partner information, and then send a federation request back to the initiator. This process shares information about the business partner and uses the token.

To verify a token received from the host partner:

  1. Send a POST request to the following endpoint: /mgmtconfig/v1/customers/{customerId}/tenant-federation/token/verify?microtenantId={microtenantId}.

  2. Provide the following in the request endpoint:

    • customerId: The ZPA tenant ID of the customer.
    • microtenantId: The unique identifier of the Microtenant. If you are within a Microtenant, you must pass the microtenantId field when making an API call to retrieve data from that Microtenant. The microtenantId can be obtained from the API Keys page, or can be obtained programmatically using the ZPA cloud service API. Access to certain operations is limited when you are within a Microtenant. If you are within the Default Microtenant, pass microtenantId as 0 when making requests to retrieve data from the Default Microtenant. If the microtenantId is not passed in the request when creating or updating a resource, then the resource is created or updated in the Default Microtenant. To learn more, see Configuring Microtenants Using API.

    For example: /mgmtconfig/v1/customers/72057595111669761/tenant-federation/token/verify?microtenantId=145260601092866314.

  3. Include the request headers to provide information about the request context:

    • Content-Type: application/json
    • Authorization: Bearer <access_token>

  4. Provide the following JSON payload and include the following details:

    • token: The Federation token generated by the business partner (guest or host) who initiated the Federation request.
    • microtenantId: The unique identifier of the Microtenant. If you are within a Microtenant, you must pass the microtenantId field when making an API call to retrieve data from that Microtenant. The microtenantId can be obtained from the API Keys page, or can be obtained programmatically using the ZPA cloud service API. Access to certain operations is limited when you are within a Microtenant. If you are within the Default Microtenant, pass microtenantId as 0 when making requests to retrieve data from the Default Microtenant. If the microtenantId is not passed in the request when creating or updating a resource, then the resource is created or updated in the Default Microtenant. To learn more, see Configuring Microtenants Using API.

JSON Payload​

{
  "token": "string"
}

Example JSON Payload​

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJjdXN0b21lcklkIjoxNDUyNjA2MDEwOTI4NjY..."
}

Example Response​

{
  "success": true,
  "partnerInfo": {
    "partnerGid": "72057595111669760",
    "partnerName": "Acme Corp",
    "partnerScopeName": "Default",
    "approvalStatus": "PENDING",
    "federationStatus": "INACTIVE"
  },
  "partnerNotes": "Federation request from Acme Corp to share PRA apps.",
  "tokenExpirationEpochSeconds": 1745265432
}

A successful response returns code 200. To learn more, see ZPA API Codes.

Approving a Partner Federation Request

To approve a partner federation request:

  1. Send a PUT request to the following endpoint: /mgmtconfig/v1/customers/{customerId}/tenant-federation/approval?microtenantId={microtenantId}.

  2. Provide the following in the request endpoint:

    • customerId: The ZPA tenant ID of the customer.
    • microtenantId: The unique identifier of the Microtenant. If you are within a Microtenant, you must pass the microtenantId field when making an API call to retrieve data from that Microtenant. The microtenantId can be obtained from the API Keys page, or can be obtained programmatically using the ZPA cloud service API. Access to certain operations is limited when you are within a Microtenant. If you are within the Default Microtenant, pass microtenantId as 0 when making requests to retrieve data from the Default Microtenant. If the microtenantId is not passed in the request when creating or updating a resource, then the resource is created or updated in the Default Microtenant. To learn more, see Configuring Microtenants Using API.

    For example: /mgmtconfig/v1/customers/72057595111669761/tenant-federation/approval?microtenantId=145260601092866314.

  3. Include the request headers to provide information about the request context:

    • Content-Type: application/json
    • Authorization: Bearer <access_token>

  4. Provide the following JSON payload and include the following details:

    • token: The Federation token generated by the business partner (guest or host) who initiated the Federation request. The provided token must match the token that was verified.
    • microtenantId: The unique identifier of the Microtenant. If you are within a Microtenant, you must pass the microtenantId field when making an API call to retrieve data from that Microtenant. The microtenantId can be obtained from the API Keys page, or can be obtained programmatically using the ZPA cloud service API. Access to certain operations is limited when you are within a Microtenant. If you are within the Default Microtenant, pass microtenantId as 0 when making requests to retrieve data from the Default Microtenant. If the microtenantId is not passed in the request when creating or updating a resource, then the resource is created or updated in the Default Microtenant. To learn more, see Configuring Microtenants Using API.

Minimum Criteria JSON Payload​

{
  "token": "string",
  "partnerNotes": "string"
}

Example Minimum Criteria JSON Payload​

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJjdXN0b21lcklkIjoxNDUyNjA2MDEwOTI4NjY...",
  "partnerNotes": "Approved. Looking forward to the collaboration."
}

A successful response returns code 204. To learn more, see ZPA API Codes.

Updating the Provisioning Status

To update the provisioning status of the partner federation request:

  1. Send a PUT request to the following endpoint: /mgmtconfig/v1/customers/{customerId}/tenant-federation/{federation_id}/provisioning-state/{status}?microtenantId={microtenantId}.

  2. Provide the following in the request endpoint:

    • customerId: The ZPA tenant ID of the customer.
    • federation_id: The unique identifier of the Federation you want to update the provisioning status for.
    • status: The provisioning status of the Federation. The supported values are:
      • APPROVED: The provisioning status of the Federation is approved.
      • DENIED: The provisioning status of the Federation is denied.
      • TERMINATED: The provisioning status of the Federation is terminated.
    • microtenantId: The unique identifier of the Microtenant. If you are within a Microtenant, you must pass the microtenantId field when making an API call to retrieve data from that Microtenant. The microtenantId can be obtained from the API Keys page, or can be obtained programmatically using the ZPA cloud service API. Access to certain operations is limited when you are within a Microtenant. If you are within the Default Microtenant, pass microtenantId as 0 when making requests to retrieve data from the Default Microtenant. If the microtenantId is not passed in the request when creating or updating a resource, then the resource is created or updated in the Default Microtenant. To learn more, see Configuring Microtenants Using API.

    For example: /mgmtconfig/v1/customers/72057595111669761/tenant-federation/approval?microtenantId=145260601092866314.

  3. Include the request headers to provide information about the request context:

    • Content-Type: application/json
    • Authorization: Bearer <access_token>

A successful response returns code 204. To learn more, see ZPA API Codes.

Updating the Federation State

To update the status of an existing Federation to active or inactive when a Federation is in an approved provisioning state:

  1. Send a PUT request to the following endpoint: /mgmtconfig/v1/customers/{customerId}/tenant-federation/{federation_id}/federation-state/{status}?microtenantId={microtenantId}.

  2. Provide the following in the request endpoint:

    • customerId: The ZPA tenant ID of the customer.

    • federation_id: The unique identifier of the Federation you want to update the Federation status for.

    • status: The provisioning status of the Federation. The supported values are:

      • ACTIVE: The status of the Federation is active.
      • INACTIVE: The status of the Federation is pause.

      To terminate a federation, see Deleting a Federation.

    • microtenantId: The unique identifier of the Microtenant. If you are within a Microtenant, you must pass the microtenantId field when making an API call to retrieve data from that Microtenant. The microtenantId can be obtained from the API Keys page, or can be obtained programmatically using the ZPA cloud service API. Access to certain operations is limited when you are within a Microtenant. If you are within the Default Microtenant, pass microtenantId as 0 when making requests to retrieve data from the Default Microtenant. If the microtenantId is not passed in the request when creating or updating a resource, then the resource is created or updated in the Default Microtenant. To learn more, see Configuring Microtenants Using API.

    For example: mgmtconfig/v1/customers/72057595111669760/tenant-federation/137629/federation-state/ACTIVE?microtenantId=145260601092866314.

  3. Include the request headers to provide information about the request context:

    • Content-Type: application/json
    • Authorization: Bearer <access_token>

A successful response returns code 204. To learn more, see ZPA API Codes.

Getting All Partner Federations

To get all partner Federations for the specified customer (both the host and guest partner):

  1. Sent a GET request to the following endpoint: /mgmtconfig/v1/customers/{customerId}/tenant-federation?microtenantId={microtenantId}&page={page}&pagesize={pagesize}&sortBy={creationTime}&sortDir={sortDir}.

  2. Provide the following in the request endpoint:

    • customerId: The ZPA tenant ID of the customer.
    • microtenantId: The unique identifier of the Microtenant. If you are within a Microtenant, you must pass the microtenantId field when making an API call to retrieve data from that Microtenant. The microtenantId can be obtained from the API Keys page, or can be obtained programmatically using the ZPA cloud service API. Access to certain operations is limited when you are within a Microtenant. If you are within the Default Microtenant, pass microtenantId as 0 when making requests to retrieve data from the Default Microtenant. If the microtenantId is not passed in the request when creating or updating a resource, then the resource is created or updated in the Default Microtenant. To learn more, see Configuring Microtenants Using API.
    • page: Specifies the page number. This field is 1 by default.
    • pagesize: Specifies the page size. If not provided, the default page size is 20. The maximum page size is 500.
    • sortBy: Indicates the parameter that is used to sort the results (i.e., creationTimeor provisioningStatus).
    • sortDir: Specifies the sort direction (i.e., ascending or descending order).

    For example: /mgmtconfig/v1/customers/72057595111669760/tenant-federation?page=1&pagesize=20&microtenantId=145260601092866314.

Example Response​

{
  "totalPages": "1",
  "totalCount": "2",
  "list": [
    {
      "id": 137629,
      "provisioningStatus": "APPROVED",
      "notes": "Federation request from Acme Corp to share PRA apps.",
      "isInitiator": true,
      "partnerInfo": {
        "partnerGid": 72057595111669761,
        "partnerName": "Globex Inc",
        "partnerScopeName": "Default",
        "approvalStatus": "APPROVED",
        "federationStatus": "ACTIVE"
      },
      "creationTime": 1744919532,
      "modifiedTime": 1744920000
    },
    {
      "id": 137630,
      "provisioningStatus": "PENDING",
      "notes": "Inbound federation request from Initech",
      "isInitiator": false,
      "partnerInfo": {
        "partnerGid": 72057595111669762,
        "partnerName": "Initech",
        "partnerScopeName": "Default",
        "approvalStatus": "PENDING",
        "federationStatus": "INACTIVE"
      },
      "creationTime": 1745000000,
      "modifiedTime": 1745000000
    }
  ]
}

A successful response returns code 200. To learn more, see ZPA API Codes.

Getting Active Federated Partners

To get a list of all active federated partners:

  1. Sent a GET request to the following endpoint: /mgmtconfig/v1/customers/{customerId}/tenant-federation/partners?microtenantId={microtenantId}&page=1&pagesize=20.

  2. Provide the following in the request endpoint:

    • customerId: The ZPA tenant ID of the customer.
    • microtenantId: The unique identifier of the Microtenant. If you are within a Microtenant, you must pass the microtenantId field when making an API call to retrieve data from that Microtenant. The microtenantId can be obtained from the API Keys page, or can be obtained programmatically using the ZPA cloud service API. Access to certain operations is limited when you are within a Microtenant. If you are within the Default Microtenant, pass microtenantId as 0 when making requests to retrieve data from the Default Microtenant. If the microtenantId is not passed in the request when creating or updating a resource, then the resource is created or updated in the Default Microtenant. To learn more, see Configuring Microtenants Using API.
    • page: Specifies the page number. This field is 1 by default.
    • pagesize: Specifies the page size. If not provided, the default page size is 20. The maximum page size is 500.

    For example: /mgmtconfig/v1/customers/72057595111669760/tenant-federation/partners?page=1&pagesize=20&microtenantId=145260601092866314.

Example Response​

{
  "totalPages": "1",
  "totalCount": "1",
  "list": [
    {
      "partnerGid": 72057595111669761,
      "partnerName": "Globex Inc",
      "partnerScopeName": "Default",
      "approvalStatus": "APPROVED",
      "federationStatus": "ACTIVE"
    }
  ]
}

A successful response returns code 200. To learn more, see ZPA API Codes.

Deleting a Federation

To delete a Federation:

  1. Sent a GET request to the following endpoint: /mgmtconfig/v1/customers/{customerId}/tenant-federation/{federation_id}?microtenantId={microtenantId}.

  2. Provide the following in the request endpoint:

    • customerId: The ZPA tenant ID of the customer.
    • federation_id: The unique identifier of the Federation you want to delete.
    • microtenantId: The unique identifier of the Microtenant. If you are within a Microtenant, you must pass the microtenantId field when making an API call to retrieve data from that Microtenant. The microtenantId can be obtained from the API Keys page, or can be obtained programmatically using the ZPA cloud service API. Access to certain operations is limited when you are within a Microtenant. If you are within the Default Microtenant, pass microtenantId as 0 when making requests to retrieve data from the Default Microtenant. If the microtenantId is not passed in the request when creating or updating a resource, then the resource is created or updated in the Default Microtenant. To learn more, see Configuring Microtenants Using API.

    For example: /mgmtconfig/v1/customers/72057595111669760/tenant-federation/137629?microtenantId=145260601092866314.

NOTE

A federation cannot be reactivated after it is deleted or terminated, and a new token-based handshake is required to reestablish a federation. The status of the federation is terminated when it is deleted.

A successful response returns code 204. To learn more, see ZPA API Codes.

Updating Federation Notes

To update the Federation notes:

  1. Sent a PUT request to the following endpoint: /mgmtconfig/v1/customers/{customerId}/tenant-federation/{federation_id}/notes?microtenantId={microtenantId}.

  2. Provide the following in the request endpoint:

    • customerId: The ZPA tenant ID of the customer.
    • federation_id: The unique identifier of the Federation you want to update the notes for.
    • microtenantId: The unique identifier of the Microtenant. If you are within a Microtenant, you must pass the microtenantId field when making an API call to retrieve data from that Microtenant. The microtenantId can be obtained from the API Keys page, or can be obtained programmatically using the ZPA cloud service API. Access to certain operations is limited when you are within a Microtenant. If you are within the Default Microtenant, pass microtenantId as 0 when making requests to retrieve data from the Default Microtenant. If the microtenantId is not passed in the request when creating or updating a resource, then the resource is created or updated in the Default Microtenant. To learn more, see Configuring Microtenants Using API.

    For example: /mmgmtconfig/v1/customers/72057595111669760/tenant-federation/137629/notes?microtenantId=145260601092866314.

  3. Include the request headers to provide information about the request context:

    • Content-Type: application/json
    • Authorization: Bearer <access_token>

  4. Provide the following JSON payload and include the updated notes string. The maximum supported characters is 1,000.

Minimum Criteria JSON Payload​

{
  "notes": "string"
}

Example Minimum Criteria JSON Payload​

{
  "notes": "Renegotiated terms on 2026-05-01."
}
NOTE

If the caller is the initiator of the Federation, the initiator's notes are updated. If the caller is the partner, the partner's notes are updated.

A successful response returns code 204. To learn more, see ZPA API Codes.

Field Descriptions

The following table includes descriptions of available fields you can use for the federating partner use cases:

FieldDescriptionRequiredValue
customerIdThe unique identifier of the ZPA tenantYesInteger
microtenantIdThe unique identifier of the Microtenant. If you are within a Microtenant, you must pass the microtenantId field when making an API call to retrieve data from that Microtenant. The microtenantId can be obtained from the API Keys page, or can be obtained programmatically using the ZPA cloud service API. Access to certain operations is limited when you are within a Microtenant. If you are within the Default Microtenant, pass microtenantId as 0 when making requests to retrieve data from the Default Microtenant. If the microtenantId is not passed in the request when creating or updating a resource, then the resource is created or updated in the Default Microtenant. To learn more, see Configuring Microtenants Using API.NoInteger
expiryTimeInSecondsThe time to live of the generated token in secondsYesInteger
The minimum supported value is 3,600 seconds (1 hour), and the maximum supported value is 86,400 seconds (24 hours).
notesThe optional notes from the initiator that are visible to the partnerNoString
partnerNotesThe optional notes from the partner used for communication between partnersNoString
The maximum supported characters is 1,000.
tokenThe Federation token previous generated by the initiatorYesString
federation_idThe unique identifier of the FederationYesInteger
statusThe provisioning status of the FederationYesEnum
Supported values:
  • APPROVED
  • DENIED
  • TERMINATED
statusThe Federation status. To learn more, see About Federated Partners.YesEnum
Supported values:
  • ACTIVE: Denotes the Active status
  • INACTIVE: Denotes the Inactive status
searchThe search string used to support search by features and fields for the APINoString
pageSpecifies the page numberNoInteger
This field is 1 by default.
pagesizeSpecifies the page sizeNoInteger
If not provided, the default page size is 20. The maximum page size is 500.
sortByIndicates the parameter that is used to sort the resultsNoString
Supported values:
  • creationTime
  • provisioningStatus
  • id
  • name
  • modifiedTime
sortDirSpecifies the sort direction (i.e., ascending or descending order)NoEnum
Supported values:
  • ASC: Ascending
  • DSC: Descending