Administrative API

Tresorit encryption platform is a service to support the rapid development of client side encryption enabled apps. Most of the cryptographic operations (including invites and sharing) must be done client side by the SDK library. To provide control over these operations, and to prevent possible abuse by tampering the client, we introduced the admin API. All client initiated changes which has a permanent effect on the server has to be approved through the Admin API (typically by the server backend of the integrated app).

There are some other cases when the admin API can be used to adjust the settings of a tresor or a user, but these cases are admin-only calls (not the client initiates it.)

Architecture

Any API call on the SDK that should have a permanent effect is not executed, only checked and saved by the platform server. The result of a call like this is an operation ID, which can be sent to the application backend of the integrated web app. The backend service then can access the Admin API with the Admin keys and use the operation ID to retrieve info about the operation and then approve or reject it. This flow splits these calls into two distinct phases, a request and an approval phase. If the request succeeds, then the request itself is syntactically and semantically correct, and the execution of the request is (at the time of the call) is possible, but the change is not effective yet. If the approval succeeds, then the change becomes effective instantaneously. Please note, that more conflicting requests may be made to the platform concurrently, and this may result in calls that can't be approved, because the approval one of the concurrent calls may make it impossible to execute the other request. This is a natural behavior of the deferred APIs, and in this case the client should retry the complete request cycle.

Administrative operations

There are two groups of administrative operations. The first group is formed by the operations used for the approval / supervision of client-initiated operations. The second group contains adminsitrative functions to track and andjust the service behavior for a single or more users or safes.

Operations need to be approved:

• User registration
• User invitation to a tresor
• Tresor creation
• Invitation link creation for a tresor
• Invitation link acceptance
• Invitation link revocation
• Kicking out a user from a tresor

Administrative queries / settings:

• Listing the user base of the tenant
• Listing the members of a tresor
• Delete a tresor
• Settings user state (enabled / disabled)
• Allow / prohibit tresor sharing for a user
• Allow / prohibit tresor creation for a user
• Upload custom content files (i.e. .css files)
• List custom content files
• Delete custom content files

Authentication

The Admin API provides a JSON webservice interface described in the next chapter. As this is a stateless web API all calls made against it has to be authenticated individually. This is done by the "Admin key signing" signature algorithm, also described in the next chapter.

Using the two admin keys

The system provides two admin keys since API v3*. The api signing can be done with any of the two keys, the system will recognize it automatically. The reason for having two distinct keys is providing rolling key change.

It's recommended to use only one of the keys (either primary or secondary). When the used key somehow leaks, it has to be changed for security reasons. The first step to change the key without downtime is to start using the other key, and eliminate usage of the compromised one. After all integrated systems has been configured to use the new key, the old one can be re-generated. (Please feel free to contact tresorit for advice about key change or for a key-regeneration.)

*For tenants created before this version their old single admin key became their primary key and a new secondary key is generated for them. Please feel free to contact tresorit for the second key.

Example

To understand the administrative workflow briefly, consider the following situation:

Prerequisites: A user is signed in to the service successfully, then started to use the integrated application.

1. The user makes changes in the App which result in the invitation of other users to a tresor (through the SDK).
2. The Tresorit encryption platform server checks this call, saves the pending data and sends back a unique operation id to the client.
3. The client then send this ID to the application server and requests the approval of it.
4. The application server then uses the administrative API to query the details of the operation, then decides about the approval or rejection of it.
5. If the operation is approved by the server (also through the admin API), and the approval succeeds, the operation takes effect instantly. Then the client can be notified about the result.

Common approval workflow

Note: If the approval fails because the preceding approval of a concurrent call, then the client should retry the request-approval cycle again.