API Configuration (Technical Document)
External API V1.0 Techdoc
This document describes the design of the 1.0 version of the external API and the integrations website, which will allow the customers to integrate their content from DeepHow into their systems.
Each customer will have access to the DeepHow Integrations portal  using the same credentials they use to access the applications (Web, iOS, Android and Windows).
This portal will be the entry point for the customer's IT department to configure their integrations with DeepHow.
Only users with the admin-organization role are allowed.
API Keys & Authorization
The external API relies on an API Key that is associated with the customers organization to perform all the requests and gather information associated with them. At any given time, the customer can delete the API Key if they think it has been compromised, making any further request with that key useless.
Apart from the API Key, the user has to call the authorization endpoint passing a valid email and password. If the information is correct, an idToken is generated. Every request should be done using the apiKey header along with the idToken as a bearer in the authorization header.
The External API is designed to work as a middleware between the customer and the DeepHow system. They will only access the information exposed by the endpoints.
A detailed description of its usage is deployed as API Doc .
List, search and details of the workflows for the customer's organization. The endpoints provide detailed information about the workflows, including a deep link to open the workflow and watch it on Deephow's website.
List the skills for the organization and get information about a user's progress.
The integrations website provides support to upload CSV files with a batch of users to create or update in DeepHow, including templates to allow the customers to associate users with teams, skills, workspaces and assign roles to each of them.
From the landing page, select the User imports option:
You will be redirected to the imports section, where you can upload CSV files, have a record of previous imports and delete them if needed.
The CSV supports the following fields:
name: This is the display name
email: The user email address
team: The name of the team that the users will be added to
team_workspace: The workspace of the team
skill_id: The ID of the skill that the users will be assigned to
workspace: The name of the workspace that the users will be added to
role: The user role for the given workspace. This is only used alongside the workspace. Without a workspace field this value is ignored.
It's possible to add users to multiple workspaces, teams and assign them to multiple skills in a single file. To do that, the entries should be specified in multiple rows, where the email field is used as an identifier to group the user data. Besides that, It's recommended to have a different CSV file for each case to avoid confusions or mistakes.
Here is a list of samples of how the CSV file should look like for each case
Assigning skills to users
Assigning teams to users
Assigning workspaces to users
Disabling users via the API
Apart from using the CSV file to disable users, it is also possible to do it via the API using a JSON payload. For more details check the Swagger documentation page.
With either approach, the user won't be able to access DeepHow anymore, even if the Identity provider from a SSO configuration allows the login.