Short description | Multitenancy

Multitenancy is a software architecture used in cloud computing. The multitenancy architecture is distinguished by the fact that a software application is divided into virtual partitions and that each client group works with a customer-specific virtual application instance.

Short description | Tenants

A PTV xServer instance can be shared by many different tenants. The server identifies these tenants and uses this information to separate tenant-specific data. For example, the xDima service stores distance matrices of different tenants but each tenant has access to its own distance matrices only.

Short description | Scopes

A scope is a user defined separation which can be used to distinguish between different applications or sections. Scopes are subordinate to tenants.


This Technical Concept is used to serve several clients (customers or principals) on the same server, without these having mutual insight into their data.

Detailed Consideration

Using scopes

The scope of a request can be set using the API. The type RequestBase has a property scope of type string. This string can be set to any value that consists of lowercase characters and digits. If it is not set PTV xServer uses the default value globalscope.

The reserved scope value allscopes must not be used as regular scope. It can only be used in list operations to retrieve data for all existing scopes.


Here is an example using xDima:

CreateDistanceMatrixRequest request = new CreateDistanceMatrixRequest(); 

Using tenants

The tenant on the other hand can not be set on the API directly. This is to avoid unauthorized access to the data of other tenants. The tenant must be specified on each request as a HTTP header named x-tenant. The idea behind this approach is that a middleware could easily add this header based on user authentication (for example Basic Authentication). Like the scope the tenant must also consist of lowercase characters and digits only. If it is not set the default value globaltenant is used.

The reserved tenant value alltenants must not be used as regular tenant. It can be used only as administrator in list operations in combination with allscopes to retrieve data for all existing tenants and scopes.


Process of using tenants

Listing data for all tenants and all scopes

Some list operations like listDistanceMatrices or listHighPerformanceRoutingNetworks support the reserved tenant keyword alltenants and the reserved scope keyword allscopes. Normally, these list operations return only data that belongs to the specific tenant and scope that is set in the request and HTTP header (if no tenant or scope is set, the data belonging to the default globaltenant and globalscope is returned).

In order to return data for all available scopes or tenants the special reserved keywords can be used:


Here is an example to list distance matrices of all scopes:

CreateDistanceMatrixRequest request = new CreateDistanceMatrixRequest(); 
API Documentation API Documentation for RequestBase