Concepts
Multi-tenancy

Multi-tenancy

Why multi-tenancy matters

The Protime platform serves many organizations simultaneously – each with its own employees, clockings, contracts, and organizational structures. An integration built for one customer must never see, modify, or interfere with another customer’s data. Multi-tenancy is the architectural pattern that provides this isolation while allowing all customers to share the same infrastructure.

Understanding the tenant model is essential for integrators because it affects how URLs are constructed, how tokens are obtained, and how data boundaries are enforced.

Tenant isolation

Each customer organization in Protime is a tenant. A tenant represents a fully isolated data partition: employees, clockings, absences, activity definitions, and every other resource belong to exactly one tenant. There is no API operation that can cross tenant boundaries.

This isolation is not merely a filter applied at query time. Tenants are separated at the infrastructure level, ensuring that even in error conditions or edge cases, one tenant’s data cannot leak to another.

Tenant identification in the URL

The tenant is identified by the subdomain in every API request:

https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/<collection>

For example, if the customer’s tenant name is acme, all API calls are directed to:

https://acme.myprotime.eu/connector/protimeapi/api/v1/...

The tenant name can be determined by looking at the URL of the customer’s myProtime end-user environment. If the end-user environment is accessed at https://acme.myprotime.eu, the tenant name is acme.

Environments

Protime provides two environments, each with its own domain:

Environment Domain Purpose
Production myprotime.eu Live data and real business operations
Sandbox myprotimesandbox.eu Testing and development without affecting production data

The full URL pattern for each environment:

  • Production: https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/...
  • Sandbox: https://<tenant>.myprotimesandbox.eu/connector/protimeapi/api/v1/...

Both environments follow the same API contract. The sandbox environment allows integrators to develop and test their integration without risk to production data.

Authentication is per-tenant

The OAuth2 token endpoint also includes the tenant name:

https://authentication.<environmentDomain>/tenants/<tenant>/connect/token

This means:

  • Tokens are scoped to a single tenant. A token obtained for tenant acme cannot be used to access data belonging to tenant globex. Attempting to do so results in a 401 Unauthorized response.
  • Client credentials are per-tenant. Each tenant has its own client_id and client_secret, issued by Protime during the onboarding process.
  • Token lifetime is independent per tenant. Expiration times are set per tenant configuration and may differ between tenants.

An integrator that serves multiple Protime customers must obtain and manage a separate set of credentials and tokens for each tenant.

Automatic data filtering

Once a request is authenticated, every API response is automatically filtered to the authenticated tenant’s data. There is no need – and no ability – to specify a tenant filter in query parameters or request bodies. The connector infers the tenant from the subdomain in the request URL and the token’s audience claim, and scopes all database operations accordingly.

This design eliminates an entire category of integration bugs: it is impossible to accidentally request or modify another tenant’s records, even if the integrator’s code contains a logic error.

Practical implications for integrators

Concern Implication
URL construction Every endpoint URL must include the correct tenant subdomain. Hardcoding a URL from one customer’s environment will not work for another.
Credential management Store client_id, client_secret, and the tenant name together as a set. Mix-ups between credentials and tenant URLs produce authentication failures.
Token caching Tokens should be cached per tenant. Reusing a token across tenants will fail.
Sandbox testing Switch the domain from myprotime.eu to myprotimesandbox.eu to test against sandbox data. No other URL or credential changes are needed if sandbox credentials mirror production.
Webhook endpoints The consumer’s webhook destination URL receives events from a specific tenant. If the same consumer serves multiple tenants, it must be able to distinguish which tenant sent each event (for example, by using a tenant-specific path or header).

Further reading

External reference modelOAuth2 scope model