Adding a Custom Integration with Torii – Part 1: Using Postman

Posted on by steveidm

In this two part blog, we are going to walk through the process of creating a custom integration with Torii. In this blog, we’ll go through the basics which I will demonstrate using Postman and in the second blog, we will demonstrate using a Google Sheet to sync directly with Torii.

Creating an API Key

In order to do a custom integration, we will need to create an API Key within Torii.

  1. Log into your Torii Admin Console
  2. Click on Settings -> API Access
  3. Click the “Generate API Key” button on the right
  1. Select Full access and click Generate Key
  1. Copy the key to somewhere safe as you won’t be able to retrieve it later.

Creating an Application Account ID

In this step, we are going create an Application ID that we can use in Postman for this custom integration.

  1. In the Integrations Tab, Click “Add Custom Integration”
  1. When you add a custom integration, you have the option to select an application that currently exists within Torii or you can create your own. In this example, I will create my own:
  1. When adding a custom application, you are required to add some additional information and then click Add Application
  1. Now you can click Add Integration
  1. You should now be presented with your Application Account ID.

Postman Overview

This blog assumes you have a basic understanding of Postman as we will not go through the process of installing or configuring Postman.

There are 4 Parts to the Custom Integration Process:

You will need to upload a JSON file to the Torii Servers. When uploading the JSON file, you will need a unique URL every time. Once you’ve uploaded the file, you will get a File ID that can be used to trigger the sync.

Step 1 – Getting a File URL and File Path.

  1. Select “GET” as your HTTP Method.
  2. Enter the URL: https://api.toriihq.com/beta/files/url?name=my_file.json&type=customIntegrationData
  3. Under Authorization, select “Bearer Token”
  4. In the Token Field Paste your Torii API key we generated earlier.
  1. Click Send
  2. In the Response, you will see both a “url” and a “filePath”. We will need both these in later steps.

Step 2 – Uploading your JSON File

In this step you need to prepare your JSON file using whatever tools or utilities of your preference. In this Postman example, I’m going to use a raw JSON message in the body of the post. You can find the schema of the JSON file at https://api.toriihq.com/beta/docs. The schema allows you to specify extra attributes such as Roles and the Last Used Date. In the licenses section, you can specify extra information such as an unassigned license block and the price per user. 

{
                    "users": [
                      {
                        "email": "steve@theidentityguy.net",
                        "firstName": "Steve",
                        "lastName": "Bradley",
                        "status": "active",
                        "externalStatus": "Active",
                        "roles": ["Admin", "Super admin"],
                        "lastUsedDate": "2021-11-04T20:43:14Z"
                      },
                      {
                        "email": "shahbaz@theidentityguy.ca",
                        "firstName": "Shabaz",
                        "lastName": "Khalid",
                        "status": "active",
                        "externalStatus": "Active",
                        "roles": ["Member"],
                        "lastUsedDate": "2021-11-04T14:43:14Z"
                      },
                       {
                        "email": "rajiv@theidentityguy.ca",
                        "firstName": "Rajiv",
                        "lastName": "Menon",
                        "status": "active",
                        "externalStatus": "Active",
                        "roles": ["Member"],
                        "lastUsedDate": "2021-11-04T14:43:14Z"
                      }
                    ],
                    "licenses": [
                      {
                        "name": "Pro",
                        "unassignedAmount": 10,
                        "users": [
                          {
                            "email": "steve@theidentityguy.net",
                            "licenseStatus": "active",
                            "lastUsedDate": "2021-11-04T14:43:14Z"
                          }
                        ],
                        "pricePerUser": 15000
                      },
                      {
                        "name": "Guest",
                        "unassignedAmount": 20,
                        "users": [
                          {
                            "email": "shahbaz@theidentityguy.ca",
                            "licenseStatus": "active"
                          },
                          {
                            "email": "rajiv@theidentityguy.ca",
                            "licenseStatus": "active"
                          }
                        ],
                        "pricePerUser": 20000
                      }
                    ]
}
  1. Select “PUT” as your HTTP Method.
  2. Enter the URL that you received in the previous step
  3. Paste your JSON (Select RAW radio button)
  4. There is no Authorization Header required for this step as the URL received in the previous step includes the authorization. Click Send
  1. You should receive a 200 OK response.

Step 3 – Getting your File ID

In this step you are going to need the File Path which was returned in Step 1 to obtain a File ID.

  1. Select “POST” as your HTTP Method.
  2. Enter the URL: https://api.toriihq.com/beta/files
  3. Under Authorization, select “Bearer Token”
  4. In the Token Field Paste your Torii API key we generated earlier.
  5. In the body you are going to post the PATH which was returned in Step 1 and the Type (customIntegrationData)
{
    "path":"1642779183321/my_file.json",
    "type":"customIntegrationData"
}
  1. Click Send
  1. In the response, you should see an ID returned

Step 4 – Syncing the Integration.

In the last and final step, you will need the Application Account ID that was created in Torii and the File ID from Step 3.

  1. Select “PUT” as your HTTP Method.
  2. Enter the URL: https://api.toriihq.com/beta/services/sync/custom
  3. Under Authorization, select “Bearer Token”
  4. In the Token Field Paste your Torii API key we generated earlier.
  5. In the body you are going to put the File ID which was returned in Step 3 and the Application Account ID which was created in the previous step. 
{
    "idFile":"205556",
    "idAppAccount":"15785"
}
  1. Click Send
  2. You should receive a Success: true response.

Verifying your Custom Integration

In Torii, under the Licenses Tab, you should now see your custom integration

In the Users Tab, you should see your Users.

One thought on “Adding a Custom Integration with Torii – Part 1: Using Postman”

  1. Pingback: Adding a Custom Integration with Torii – Part 2: Using Google Sheets – Steve The Identity Guy

Comments are closed.