Overview

Before starting, we recommend reading the Introduction to Custom Integration article and visiting our Developer Portal for a detailed step-by-step guide on building your first custom integration.

Kindly remember that custom integrations:

• DO support syncing users, licenses, roles, and last used dates
• DO NOT support syncing expenses and contracts, even if the integrated app contains this data
• Work best for onboarding/offboarding/license optimization scenarios

To build your own integration and push user and license data into Torii you will need to follow the below process.

Note, steps 3 & 4 require some technical knowledge. We recommend they are done by a developer. 

IT - Setup/ Preparation

• STEP 1 - Get a Torii API key
• STEP 2 - Create the basis for a new custom Integration in Torii

Technical - Use the API to upload and sync users

• STEP 3 - Upload the data to Torii
• STEP 4 - Sync the data to Torii

STEP 1 - Get a Torii API Key

Prerequisite - Torii admin permission is required

1. Go to Settings >> API Access
2. Click on Generate API key
   
   
3. In Generate API Key make sure you select:
   1. Key Type: Torii API
   2. Permission: Full access
   3. Expiration date: We recommend at least 1 year into the future
   4. Description: Enter what integration this will be used for
      
4. Click Generate key. Make sure you store the API key somewhere safe because you will not be able to see it again after step 5. If, for some reason, you ever lose your API key, you can always generate a new one.
   
5. Click Got it

STEP 2 - Create the basis for a new custom Integration in Torii

1. Go to the Integrations page,
2. Scroll down and click the ADD CUSTOM INTEGRATION tile
   
3. Find the App you want to integrate using the search row
4. Click Get Started
   
   
   
5. Copy the App account ID and store it somewhere safe
   
   
6. Close the window
   
7. Once you close the window, you'll see that Torii created a placeholder integration that is waiting for you to upload data to. Please note: you must complete steps 3+4 to see your data in Torii.
   
   
   

STEP 3 - Upload the data to Torii

Prerequisites - Generate a JSON file named ‘users_file.json’ in the working folder and verify it complies with the "File schema". Click here for Torii's full API documentation

💡 Make sure you replace the placeholders in the API calls with your variables, e.g. replace API_KEY with the API key you generated in step 1.

There are 2 techniques you can use to upload the data to Torii

1. For files up to 3MB - use the Upload File (up to 3MB) API or run the following command:

   curl --request POST "https://api.toriihq.com/v1.0/files/upload" \
   --header "Authorization: Bearer API_KEY" \
   --header "Content-Type: multipart/form-data" \
   --form 'type="customIntegrationData"' \
   --form 'file=@"FULL/PATH/TO/FILE"'

2. For files larger than 3MB, follow the process below:
   1. Create a one-time URL upload link
   2. Upload the file to S3
   3. Update Torii with the upload information

1. 1. Create a one-time, private URL upload link - use the Get parameters for uploading files API or run the following command:

      curl "https://api.toriihq.com/v1.0/files/url?name=users_file.json&type=application/json" \ 
      --header "Authorization: Bearer API_KEY" 

      You should get a response that looks like this:

      {
        "uploadFileParameters": {
          "url": "https://torii-app-test.s3.us-west-2.amazonaws.com/uploads/23/1704790932720/users_file.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAWVLDEIRX6X6UEP5I%2F20240109%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20240109T090212Z&X-Amz-Expires=300&X-Amz-Signature=09c8a054052a4c069a40f0ada5771742bb3f38ee12a6974e7cfbbef08ad9726c&X-Amz-SignedHeaders=host&x-amz-acl=private&x-id=PutObject",
          "filePath": "1704790932720/users_file.json"
        }
      }

      The url is used in step 2 and the filePath is used in step 3.
      

      Note

      • These parameters are embedded in the upload file parameters; consider it when

      writing the code.

      • The upload URL is valid for a short period of time, so make sure to upload the file

      before it expires.
      
      

   2. Upload the file to S3 - use the url from the response and run the following command:

      curl --request PUT S3_URL --data @'FULL/PATH/TO/FILE' 
      // Example 
      curl --data @'/Users/user/Downloads/users_file.json' -X PUT "https://torii-app-test.s3.us-west-2.amazonaws.com/uploads/23/1704790932720/users_file.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAWVLDEIRX6X6UEP5I%2F20240109%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20240109T090212Z&X-Amz-Expires=300&X-Amz-Signature=09c8a054052a4c069a40f0ada5771742bb3f38ee12a6974e7cfbbef08ad9726c&X-Amz-SignedHeaders=host&x-amz-acl=private&x-id=PutObject"

      Note

      If you are pasting the URL in your terminal, make sure it doesn’t add any escape characters (e.g. \)

      
      
      
   3. Update Torii with the upload information - use the Store file information in DB API or run the following command:

      curl "https://api.toriihq.com/v1.0/files" \ 
        --header "Authorization: Bearer API_KEY" \ 
        --header "Content-Type: application/json" \
        --data '{"path":"S3_FILE_PATH","type":"customIntegrationData"}'

      
      You should get a result with the Torii upload ID like in the below example:
      
      Save the id value for step 4

STEP 4 - Sync the uploaded file to Torii

1. Use the Sync custom integration API or run the following command:
   

   curl --request PUT "https://api.toriihq.com/v1.0/services/sync/custom" \
     --header "Authorization: Bearer API_KEY" \
     --header "accept: */*" \
     --header "content-type: application/json" \
     --data '{"idFile":"FILE_ID", "idAppAccount": "APP_ACCOUNT_ID"}'

2. Replace the API_KEY, FILE_ID from the previous step (Upload ID)
3. Replace the APP_ACCOUNT_ID you received from Torii in STEP 2 (add custom integration) like in the below example:
   

You should get a response indicating that the operation was successful, like in the below example:

Error Message: in case of an error, a relevant message like "Illegal file structure, Wrong file id, Wrong account", etc. will be displayed.

Once all these steps are completed, you will see your application data in the custom integration in Torii.

Additional Notes

1. The syncs are not incremental, meaning that on each sync you must provide all the users you currently have in the systems (and not only new ones for example)
2. Custom integration data does not update automatically - you must sync data each time you want to see fresh data in Torii. You can automate this process using a 3rd party tool. 
3. It may take some time for the sync to complete. To confirm a successful sync, Go to Integration window (1) and make sure the hourglass (2) disappeared and a green checkmark (3) is displayed.
   

Q & A

Q: Can I sync absolutely any app with Torii?
A: Yes, as long as the data is structured according to the Torii file schema.

Q: How often will data be pushed into Torii & Does Torii support date synchronization with custom integrations?
A: You can decide how often you want to push the data into Torii. We recommend pushing the data regularly, so it stays up to date. When data has not been synced for more than 10 days, we show an alert in the UI.

Q: Can I perform workflow actions for a custom app?
A: Yes, through custom action configuration

Q: What happens when disconnecting custom integration?
A: The app account is revoked, and no more syncs are possible. You can always reconnect the same account. Read this article to learn what happens to your data when you disconnect an integration

Q: How do I delete and update users?
A: Each time a new file is pushed, the old data is overwritten. If users were removed from the file - they would be removed from the app in Torii. If user attributes were updated in the file - they will be updated in Torii.

File schema

The file should include the following information. Note that fields must have the exact field name as shown in the following table:

User

License

License User

Return up