Manage users provisioned to a custom integration

Productiv automatically determines provisioned users for apps supported by our connector library. We also provide the ability to create and edit this list directly for a custom integration via the developer APIs. This enables two main use cases: tracking provisioned users for applications not supported by Productiv's connectors and gaining direct control over the process for determining provisioning.

This guide will walk through the process of creating, editing, and viewing the list of users provisioned to a custom integration.

Prerequisites

Before this API can be queried, you should have already set up the application for which you will be publishing provisioned users. Once that's done, you should have a unique appId that can be used to query these APIs. To see how to set up an application check out Set up an Application.
All developer APIs require a Bearer access token as part of each request's headers. To see how to generate an authorization token, check out Authorization. The scope https://api.productiv.com/connector.write is needed for the endpoints mentioned in this guide. This token expires after a certain amount of time; when the token expires a new one must be generated.

Adding provisioned users

Adding provisioned users for a custom integration can be done by making a POST request to the Publish provisioned users endpoint. We will be adding the following users:

const provisionedUsers = [
  {
    appUserId: "123",
    email: "appuser1@domain.com",
    username: "userOne",
    license: "Pro",
  },
  {
    appUserId: "112",
    email: "appuser2@domain.com",
    username: "iAmUserTwo",
  },
  {
    appUserId: "221",
    email: "appuser3@domain.com",
  },
];

For a definition of the user objects that can be sent in this request, see the ProvisionedUser object section of the endpoint's reference. Note that a maximum of 1000 users can be added in a single request, so multiple POST requests must be used when there are more than 1000 total users.

This list of users can be uploaded to Productiv using the following code snippet.

const axios = require("axios");
const bearerToken = "some_token"; // see Authorization guide for generating a bearer token

const appId = "some_app_id"; // provided by Productiv after creating a custom integration

const addProvUsersURL = `https://public-api.productiv.com/services/push/v1/customer/apps/${appId}/users`;

const headers = {
  "content-type": "application/json",
  Authorization: `Bearer ${bearerToken}`,
};

const data = {
  provisionedUsers,
};

(async () => {
  const res = await axios.post(addProvUsersURL, data, { headers });

  if (res.status !== 200) {
    console.error("Failed to publish provisioned users");
  } else {
    console.log("Successfully published provisioned users");
  }
})();

Upon a successful POST request, these users will be reflected in Productiv's system within 24 hours of the time they were uploaded.

Getting the provisioned users

After waiting 24 hours, we can view our set of provisioned users by using the Get provisioned users endpoint.

This can be done with the following snippet.

const axios = require("axios");

const bearerToken = "some_token"; // see Authorization guide for generating a bearer token

const appId = "some_app_id"; // provided by Productiv after creating a custom integration

const getProvUsersURL = `https://public-api.productiv.com/services/push/v1/customer/apps/${appId}/users`;

const headers = {
  "content-type": "application/json",
  Authorization: `Bearer ${bearerToken}`,
};

(async () => {
  const res = await axios.get(getProvUsersURL, { headers });

  if (res.status !== 200) {
    console.error("Failed to get provisioned users");
  } else {
    console.log(res.data);
  }
})();

This should output the following.

{
    "success": true,
    "provisionedUsers": [
        {
            "appUserId": "123",
            "email": "appuser1@domain.com",
            "username": "userOne",
            "license": "Pro"
        },
        {
            "appUserId": "112",
            "email": "appuser2@domain.com",
            "username": "iAmUserTwo"
        },
        {
            "appUserId": "221",
            "email": "appuser3@domain.com"
        }
    ],
    "nextPageToken": null,
    "numUsers": 3
}

Since we only have 3 users provisioned for our integration, the nextPageToken is set to null. This endpoint returns a maximum of 1000 users, so If we had more than 1000 users provisioned for our integration we would need to use the nextPageToken provided in each response to get subsequent pages of users. The following code demonstrates a way to get the entire list of users.

// URL and header definitions left out for brevity
(async () => {
  let nextPageToken = null;
  const allUsers = [];

  do {
    const res = await axios.get(getProvUsersURL, { headers });

    if (res.status !== 200) {
      throw new Error("Failed to get provisioned users");
    } else {
      allUsers.push(...res.data.provisionedUsers);
      nextPageToken = res.data.nextPageToken;
    }
  } while (nextPageToken !== null);

  console.log(allUsers);
})();

Deleting provisioned users

As time progresses, you may decide that a previously provisioned user is no longer provisioned for the application. The Delete provisioned users endpoint allows you to remove users from the set of provisioned users. Note that this endpoint has a similar limitation of being able to delete 1000 users in a single request and that any modification to the set of users may take up to 24 hours to appear.

In order to delete users, you must provide a list of user objects as part of a DELETE request. These user objects are defined here, and it is sufficient to provide only an email and appUserId for each user to delete them.

The following code will delete 2 of the 3 users we provisioned to our integration.

const axios = require("axios");

const bearerToken = "some_token"; // see Authorization guide for generating a bearer token

const appId = "some_app_id"; // provided by Productiv after creating a custom integration

const deleteProvUsersURL = `https://public-api.productiv.com/services/push/v1/customer/apps/${appId}/users`;

const headers = {
  "content-type": "application/json",
  Authorization: `Bearer ${bearerToken}`,
};

const usersToDelete = [
  {
    appUserId: "112",
    email: "appuser2@domain.com",
  },
  {
    appUserId: "221",
    email: "appuser3@domain.com",
  },
];

const data = {
  provisionedUsers: usersToDelete,
};

(async () => {
  const res = await axios.delete(deleteProvUsersURL, data, { headers });

  if (res.status !== 200) {
    console.error("Failed to delete provisioned users");
  } else {
    console.log(res.data);
  }
})();

If successful, we should see the following output.

{ numUsersDeleted: 2, success: true }

After waiting 24 hours for our changes to take effect, we can again query the list of users (see the above section). Doing so will give us the following list of users.

[
     {
            "appUserId": "123",
            "email": "appuser1@domain.com",
            "username": "userOne",
            "license": "Pro"
        }
]