All programmatic interaction with the Disruptive Technologies API is done via a logged-in Service Account.
Once logged in, the program talking to the API will be able to perform operations that are within the access level of the role granted to the Service Account.
Creating a Service Account
All Service Accounts are created within a Studio project. To create a Service Account requires at least project developer access to that project and it can be done either manually via Studio or via the API.
To create a Service Account in Studio, navigate to Service Accounts under API Integrations in the menu on the left and press Create new.
A new Service Account have only a few fields populated:
Display name - A readable name that can be used to present the account in a list. When a Service Account is granted access to a project, this name will be shown in the access list of that project.
Service Account email - The address of the Service Account, which is all that is needed to grant rights to the account. This email is generated by the system when the account is created and cannot be changed by users.
To further configure the Service Account, you have:
Active Keys - A list of Key / Secret pairs which must be used when logging in as the Service Account.
Enable Basic Auth - Allows the Key / Secret combination to be used as a username and password with HTTP basic auth scheme for simplified authentication during prototyping.
Notably, the Service Account does not have any access rights when created - not even to the project it resides in. In fact, there are no connections at all between the project the Service Account exists within and the projects it is granted access to.
Controlling access rights
Access to the Project that the Service Account resides in is controlled directly via the role in the current project. It has No Access by default, so to give it read access to the current project, it has to be changed to at least have project user access.
Access to all projects in an organization
If you want the Service Account to have access to all projects in an organization, then:
- Copy the Service Account email.
- Navigate to Organization details via the top menu.
- Paste the Service Account email into the form and press Add administrator.
The Service Account now has the same level of access as an organization administrator.
Log in as a Service Account
There are two ways to log in using a Service Account: OAuth 2 for production integration and Basic Auth. for simple rapid development.
OAuth 2 flow
You should always use the OAuth 2 authentication flow in a production environment. To do this, your code needs to be able to acquire an Access Token - as described separately in the article on Authentication.
When you have acquired the Access Token, you can access the API as that Service Account by attaching it as a bearer token.
For rapid development, we offer easy access via Basic Auth. To do this:
- Check Enable Basic Auth
- Create a Key / Secret pair and note down both
- Authenticate with the API using Basic Auth. and send in the key as the user and the secret as the password.
This way you can easily use any API client to start making requests towards the API.
Please do not use this authentication method in real production integration. Outside of active development, please use the above OAuth 2 flow for integrations instead.
Possible use of Service Accounts in system integrations
The project that a Service Account is created within dictates who owns and can log in as the Service Account but the access rights of the Service Account itself, what projects and organizations it has access to, is completely decoupled from the owning project.
This simple separation can be very useful when it comes to sharing access, both inside and between organizations.
Within a single company
A single company operates a number of sensors in different installations for different purposes. They may choose to create a Service Account for each of their data systems and store the credentials for these Service Accounts with the config secrets of each system. Thus all access from their systems will go through a well defined named account for each system.
As each system logs in via its own Service Account, they can limit which projects each system sees - e.g. to separate development, staging and production setups - or to have some systems only have read-only access while others have admin-rights. They control this by carefully granting access to each Service Account only to the projects its system requires.
These Service Accounts may all reside in a single “System Service Accounts” project - or they could be spread out to reside in projects related to what they are used for. Regardless of which projects the Service Accounts resides in, the data systems will only be able to access the resources granted to the Service Account they have credentials for, thus limiting sources of error.
The company could also be completely relaxed and create a single Service Account “Company Master Access” - grant it organization-level access to their own organization - and put its credentials in a shared file that all their systems could access. With this approach, any system in their company would have full API access to all their projects.
Just as a project administrator can invite any user by their email to get access to a project, any Service Account can also be granted access to a project or organization.
It does not matter who owns the Service Account, as long as the email address of the Service Account is available to the granter of rights.
Company A may e.g. provide a service to Company B which requires Company A’s systems to access some or all of Company B’s projects. Using Service Accounts this can be accomplished in a safe manner.
An example approach that would solve this in an orderly fashion.
We assume that the service Company A would like to provide a monitoring and alerting service to Company B.
Company A creates a project called “Client B” in their DT Studio. Inside the “Client B” project they create a Service account called “Client B Access from Company A”.
The key/secret credentials for this Service Account is copied to the monitoring system which will allow is to log in and access the DT API as this Service Account.
Company A provides Company B with the email address of the “Client B Access from Company A” account and request that they grant e.g. Admin-access to that account for all the projects Company A should monitor.
After Company B has complied and granted access to the projects, Company A’s monitoring system will be able to log in using the “Client B Access from Company A” Service Account and list both the projects and the sensors within them. As admin of these projects, the monitoring system will also be able to setup Data Connectors to feed sensor data or even move sensors between the projects it is admin of.
Organization admins at Company B can at any time revoke the access to the Service Account from any of their projects.
Company A can at any time rotate key/secrets as part of their security routine or allow other systems of theirs to access the Company B data through the Service Account. Only people (or systems) that are given access to the “Client B” project will be able to create new access keys for the Service Account.
A simplified approach
Company A is not required to use multiple Service Accounts. It could, in fact, have a single Service Account and hand out that same Service Account email address to all its clients. The single Service Account could even just reside in the Company A’s inventory project.
With this approach Company As monitoring system would see all DT Projects from all Company A’s clients through the same account. E.g. when running the /projects list, projects from various clients would be returned in the same list.
The risk of mixing up data from various clients would probably be higher with the simple approach, but for some applications, this might not be an issue.