Using the Integrations API to share Broker tokens between Snyk organizations

A common Snyk Broker architecture is to use the same single Broker client for multiple Snyk organizations:

This architecture reduces the number of Broker client instances you need to monitor and maintain, resulting in saving operational costs.

This articles describes how to build such an architecture, sharing the same Broker token between multiple integrations.

Note: For the Private Package Repository / Registry brokers, there's a limitation where it can't be use the same broker token within existing organizations in a bulk process.

Step 1: Create an integration with a shared Broker token

To create an integration with a shared Broker token:

Add a new integration that uses Broker, using the add-new-integration API.
Make the following call:

POST https://snyk.io/api/v1/org/orgId/integrations

with the following body:

{
   "type": "github-enterprise",
   "broker": {
       "enabled": true
   }
}

The call returns the following response, that contains the new integration id and Broker token:

{
    "id": "9a3e5d90-b782-468a-a042-9a2073736f0b",
    "brokerToken": "4a18d42f-0706-4ad0-b127-24078731fbed"
}

Clone the new integration to the other organizations that you want to share the token with, using the clone-an-integration API.
Use the previously returned integration id to make the following call:
```
POST https://snyk.io/api/v1/org/orgId/integrations/integrationId/clone
```
Parameters

orgId: the Id of the organization to copy the integration settings from
integrationId: the Id created for the specific integration to copy the settings. It can be found in the Snyk Web App -> Integrations -> Integration settings (for a particular example)

Also, please use the following payload (add the Id of the organization where the integration settings will be copied to):
```
{
  "destinationOrgPublicId": "<OrgId>"
}
```
Note: To find your API Key (token) to authorize the API Call, please go to https://app.snyk.io/account.

The call returns the following response, that contains the new integration id:
```
{
    "newIntegrationId": "9a3e5d90-b782-468a-a042-9a2073736f0b"
}
```
Run the Broker client within your infrastructure, using the newly generated Broker token that was returned in the first step.

Step 2: Rotate a shared Broker token

To rotate a shared Broker token without causing downtime:

Issue a new and unique provisional token for the brokered integration, using the provision-new-broker-token API.
Make the following call:
```
POST https://snyk.io/api/v1/org/orgId/integrations/integrationId/authentication/provision-token
```
The call returns the following response, that contains the newly provisioned token:
```
{
    "id": "9a3e5d90-b782-468a-a042-9a2073736f0b",
    "provisionalBrokerToken": "4a18d42f-0706-4ad0-b127-24078731fbed"
}
```
Make sure there is no other token that is currently provisioned within the group, otherwise, this operation will fail.
Rerun your Broker client with the newly provisioned token.
Switch the existing shared broker tokens with the provisioned token, using the switch-between-broker-tokens API.
Make the following call:
```
POST https://snyk.io/api/v1/org/orgId/integrations/integrationId/authentication/switch-token
```
This action switches the Broker token for the specified integration, and for all integration within the group that share the same Broker token.
Note: this action requires a provisioned token for this integration within the group.

Articles in this section

Step 1: Create an integration with a shared Broker token

Step 2: Rotate a shared Broker token