Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

OX Cloud Provisioning Introduction

OX Cloud Provisioning Use-Cases And Concepts

Provisioning means creating, changing and deleting "informations" on OX Cloud. This is primarily done via a SOAP interface. 

There are many ways to review and explain provisioning on a Cloud system. Technically, commercially, user view, admin view, based on the APIs or the UIs.

The idea of this document is to combine them and give the right hints to the respective documentation especially to the "hands on" sections. You will find some colored boxes on the right side, that give some additional hints.


Gives you a link to the technical documentation with code examples and more technical details. Like the one below directly guides you to the technical documentation

OX Cloud "hands on" Provisioning - Start

titleUI Remark

Gives you small hints in regards to UI development

titleAPI Remark

Gives you small warnings about things you need to keep in mind, when developing against the APIs

If you want to jump to a specific topic, the list below might help you. Otherwise the document should guide you through the necessary steps to successfully provision and manage users on OX Cloud.

Table of Contents

OX Cloud was built to host and manage multi-million mailboxes. The beauty is, that those can be provisioned and managed from different sources. This is possible, because we have different administration levels, which give us the flexibility to allow that kind of operations.

OX Cloud concept of administration levels

OX Cloud consists of three administrative levels.

Root LevelThis level is purely OX managed. You don’t have to bother with this.
Brand LevelFor OX Cloud this is also managed by OX. For some parts we require your input (and you will be asked if we do so), but other than that, you also don’t have to bother with this layer. If you think you need bigger influence on that level, you might actually want to consider OX Cloud Pro.
Reseller (or Sub-admin) LevelThe reseller or sub-admin level is the one, which is managed via APIs from the respective management tools. And if you read this, you maybe want to create one at the moment.

To do the provisioning, you will have to authenticate the client you use with your admin credentials. This obviously also means, that the first requirement to actually provision users into OX Cloud is, that you have reseller credentials for your company to be able to use the API.

Please contact your OX representative to get the respective information.

Together with the login and password you will also receive the provisioning URL to be used by all SOAP requests. In addition, it is required that you give us a list of IP addresses or network(s) that should be allowed to access the provisioning system.


Here is, how you then can retrieve the WSDL files:

How to retrieve Service Definitions

Let’s dig into the OX world now.

What is a Context and how do you use it?

OX Cloud concept of Contexts

In order to provision users into OX Cloud, it is important to understand, that OX Cloud is designed for shared hosting environments in a way that it has to serve multiple tenants. You could also call it customers or domains, depending on how you look at those and name them currently.

In OX Cloud, we call that a Context. A Context is a sealed container for users. Users in a Context can’t see users of other contexts, nor can they share data with users of other contexts (except, of course, with the sharing feature, which is working exactly the same way for totally external guests as for users in other Contexts).

A usual scenario is to have a company, a family or in general one end customer in a Context. One can also say, a Context is a domain, and usually that makes sense, since a company has one domain. However, Open-Xchange Contexts are not limited to one domain only.

Let’s configure the global branding.

titleAPI Remark

Important: In OX Cloud, the name of the context must always start with your subadmin login with an underscore appended. E.g. when your subadmin login is johndoe, all your context names must start with johndoe_!

Configure global basic branding

There are some configurations which should typically be global to your own brand and are recommended to be set globally. (Those can be also set or overridden for a context if required but any later change to them need to be performed for those contexts.)

To modify those a special SOAP API endpoint can be used.


Find examples for brand configuration here:

Own brand configuration

Let's create a Context.

Create a context

Creating a context requires to create the first user in that context, which is the Context admin.

The Context admin is like an ordinary OX Cloud user, except that it can add, remove and edit users and groups within OX Cloud using the provisioning API. In addition, it inherits shared data of users, that are deleted. In OX Cloud, however, the Context admin cannot read, send or receive mail.

This means, that in practice this user actually only “lives” in the tool you are creating for this. The interactions take place in OX Cloud, but can only be initiated from the UIs you provide to your customers.

This results in this list of mandatory settings to create a context:

  • context-name [name of the Context]
  • name [login name of the Context admin]
  • password [password of the Context admin]
  • email [email address of the Context admin (remember there is not a real mailbox, but the API requires that attribute still. Thus something like is sufficient. Important: do NOT use an email address which might be used for a regular user because email addresses have to be unique.)]
  • displayname [displayname (usually first name last name)]
  • first name
  • last name
  • mail-quota [Quota for Mail in MB]
  • file-quota [Quota for Files in MB]

While these two are optional, but still often used to change the default directly:

  • lang [language, e.g. en_GB, en_US, de_DE, ...]
  • timezone [Java timezone such as Europe/Berlin]

For certain situations it might be helpful to create “two” accounts for the Context admin:

  • The “technical” Context Admin → That is needed for CRUD operations in the Context.
  • The “normal” user the Admin could also be → That can send and receive mails in a Context. See “Create Users” section below.


Find examples for Context creation here:

How do I provision a new context?

titleUI Remark

Quota is usually defined by the package you offer to your customers and thus is not necessarily as input for which you would require a separate UI field.

The same is true for the Context admin email address.

titleAPI Remark

Due to the architecture of OX Cloud, a login/username must be unique across all created contexts. That means it is not possible to create two "oxadmin" accounts.

The typical solution is to use email addresses as usernames which makes sure those are unique by definition.

titleUI Remark

Depending on other user flows and UI elements, the admin information could be pre-filled or not necessary at all. Otherwise the admin administration and the normal user administration should be rather identical and should contain following information:

titleUI Remark

Depending on how your customers will use your provisioning tool, the “normal” user account might be needed or irritating. Both views are valid depending on the use case.

In doubt, you could also add a checkbox field and only create the “normal” mailbox on request.

And last but not least we should clarify, how you can find your Context ID (which will be needed a lot in the following steps!)

Context ID

The Context ID is a numerical ID bound to the context. It is automatically generated by the OX Cloud system and is a return value of the Context create.


Identify your Context ID

How do I find my Context ID?

Next step would be to add more “normal” user accounts.

titleAPI Remark

The Context ID can be cached within your data set, but this ID also could change in rare circumstances (e.g. internal OX Cloud platform migrations) so to be always on the safe side it is highly recommended to be looked up on demand from the OX Cloud infrastructure.

What is a User and how do you create them?

OX Cloud concept of Users

Email without Users to send and receive messages is obviously not very useful. That means obviously also OX Cloud allows to create, update and delete users. In OX Cloud a user is an entity that belongs to a context and has authority to use one or more functionalities (modules) inside OX App Suite. Every user will have a user name and a User ID and is managed by the context admin. User login names must be unique within a brand and thus it is recommended to use the email address or any other unique identifier as login name. A user can share data with other users in the same context.

Display names of users must even be unique within a context. This is because it is used e.g. in the shared folder list of e.g. Calendar, Drive or Contacts in OX Cloud and is also used as folder name when mounting OX via WEBDAV. It is no problem, however, to have one "Steve Smith" in one context, and another "Steve Smith” in another context.


Create Users

Create “normal” users requires a similar set of parameters and settings like for the Context admin. But we will see a new elements, which will be explained below: The Module Access Name (moduleaccess).

Additionally we will have to clarify, how to use domains within the mail addresses.

Here is the list of settings:

  • context-name [name of the Context]
  • context-ID [Numerical ID of the Context]
  • name [login name of the Context admin]
  • password [password of the Context admin]
  • email [email address of the “normal” user]
  • displayname [displayname (usually first name last name)]
  • first name
  • last name
  • mail-quota [Quota for Mail in MB]
  • file-quota [Quota for Files in MB]
  • moduleaccess [defines the package / functionalities the user can use]
  • class of service [part of the package definition like moduleaccess]

While these two are still optional, it might be worth changing the default directly:

  • lang [language, e.g. en_GB, en_US, de_DE, ...]
  • timezone [Java timezone such as Europe/Berlin]

Next stop moduleaccess

titleUI Remark

Is and Administrator taking care of entering the End-User information or do you want to provide a Self-Service portal? Do you want to allow bulk or CSV uploads?

Most of the time a simple and clean user list is sufficient, as e.g. here:

titleUI Remark

As mentioned are language and timezone optional. You could use the account information or allow individual settings. The user will be still able to change the settings within AppSuite, so this is a convenience feature only.

Module Access Names

As mentioned above the Module Access Names define which feature set a user can access in OX App Suite on OX Cloud. When you create a context, you define which feature set will be the default for users within that context. The context's module access combination can later be overwritten for every user in the context (again with a module access combination) granting them more or fewer rights than the context defaults. This would allow you, for example, to offer combined packages, where office workers have access to OX Drive and OX Documents, while for field staff access to OX Mail and OX Calendar might be sufficient.

The basic set of functions, which is identical for all modules, contains OX Mail, OX Address Book, OX Calendar, OX Tasks, OX Document Viewer, OX Portal and the respective OX Mail and Sync Clients for Mobile Platforms.

The above mentioned set of functions is summarized under the Module Access Name "cloud_pim". Cloud for OX Cloud reasons and PIM stands for "Personal Information Manager" (NOT Product Information Management) and usually groups the afore mentioned functions in one software tool.

Beside "cloud_pim" there are three other Module Access Names you can use on OX Cloud. 


OX Mail, OX Address Book, OX Calendar, OX Tasks, OX Document Viewer, OX Portal
cloud_productivitycloud_pim + OX Documents and OX Drive (and Drive Apps)
cloud_securitycloud_pim + OX Guard
cloud_productivity_securitycloud_pim + cloud_productivity + cloud_security

Please have a look at the OX App Suite documentation if you need further information about one of these Modules. 


More Details and how to use Module Access Names to provision Users into OX Cloud can be found here:

OX Cloud Module Access Combinations

Let us talk about quota now.

titleUI Remark

If and how you have to provide UI elements for this, really depends on your specific offering and if you want to offer and allow "upsell". 

titleAPI Remark

Note: In the current Dev systems the available modules are different and called:

  • groupware_standard
  • groupware_advanced
  • groupware_premium

While those also defer in regards to functions, the principle of operation is identical and thus should not be a problem. 


In mail and especially in OX terms "quota" refers to the amount of storage a user is allowed to use. For other use cases we are able to differentiate between mail quota (the storage space a user can use for his mails) and file quota (the storage space he can use for files e.g. in OX Drive). On OX Cloud we only allow typically assume "unified quota". This means the user can use can use the allocated amount of storage space for mails and files alike. This reduces the overhead of managing different quota types in front- and back-end.

User ID

Analog to the Context ID the User ID is a numerical ID that identifies a user. It is necessary for all change operations of a user.


Identify a User ID

How do I get my User ID?

User Permissions

Sometimes it is not sufficient to create or delete a user. Sometimes mail accounts get hacked and are used to send spam messages, but you don't want to delete years of mails of that user. Or even more simple: Sometimes customers only pay, if they don't have access to necessary information anymore. Or, as a last example, you don't want to allow your users using any other mail client than the web client, because you want them to log-in via your website daily.

For those kind of use cases, OX Cloud provides User Permissions. The following User Permission can be either enabled or disabled for every user:



SENDUser is allowed to send mail
RECEIVEUser is allowed to receive mail
MAILLOGINUser can login using IMAP from external; webmail is not affected
WEBLOGINUser can login to OX webmail.


Enable User Permissions:

How do I enable User Permissions?


Disable User Permissions:

How do I disable User Permissions?

The next chapter could have been also the first chapter. Because if there is no domain, there is no mail address, but also without a user there is no mail address. Classical chicken and egg problem. However, we take care about Domains now...

How do handle Domains on OX Cloud?

OX Cloud Domain Types and Concepts

Short note about mail domains in general on OX Cloud:

The system validates every email domain name whether it conforms to RFC 2822. However, it does not validate whether the domain already exits outside OX Cloud. The provisioning system and operator is responsible for the logic to prevent misuse by the end customer.

First of all, we should have a short look on the different use cases here and allow you to decide, which is the one, that is important for you.

A) Standard Domain - Your domain, your mail

This use case is the standard (thus the name) for most installations. Your customer buys a domain and wants to use mail? Here you go. The daily business of most ISPs / Hosters worldwide.

B) Shared Domain - One domain for all

You know this use case from Gmail or Telcos that offer you a free mail service. All users have the same domain, but they are not a "group" or "company", thus they do not see automatically any information from others with the same domain ending e.g. in their address book or calendar.

C) Explicit Domain -  One domain for all of a certain group.

Explicit domains are similar to shared domains with the exception that you have to use an API call to explicitly allow to use that domain for one or more contexts. To describe one potential use-case: There is a company group (e.g. Companyname Inc., Companyname S.r.l. and Companyname AG). For reasons (e.g. organizational or legal) each legal entity needs to be in a separate Context, but should be allowed to use as their mail domain. To allow this, but at the same time prohibit, that the domain is accidentally used by others you make it an Explicit Domain.

Let's move to the first use case.

Standard Domain

As explained earlier in order to create a user in OX Cloud, you have to set an email address for that user. This will directly lead into a domain to be created into OX Cloud, bound to that user and his Context, if that domain does not already exist and is owned by a different context.

There's no specific API call and the domain is created automatically as soon as you create a user within a Context with an email address. These domains can only be used in one single context. As there is no specific API and this is the default behavior, this is the OX Cloud standard.

To illustrate what this means, here is a short listing what happens if you try to provision users to respective Contexts (in the listed order):

  1. Context1:
    1. user11 email =  → OK
    2. user12 email = → OK
  2. Context2:
    1. user21 email = → Fail
    2. user22 email = → OK
    3. user23 email = → OK
  3. Context3:
    1. user31 email = → Fail
    2. user32 email = → Fail
    3. user33 email = → Fail

Adding a user with an email address means that the domain name specified in such an email address can only be used in this single Context. If you try to create a user in a different Context with an email address containing this domain it will fail.

Now let us look at the Shared Domains.

Shared Domain

If you want to use a Shared Domain for all your users, one point from the very beginning is not correct. You do not have to create a Context first, but the Shared Domain. Creating a shared domain means, that you can use the same domain across all contexts within your Sub-admin Level.


As a first step you have to create your Shared Domain via an REST API

API Documentation for Shared-Domains

After that you continue as above with creating a Context and Users.

To illustrate what this means, also here a short listing what happens if you try to provision users to respective Contexts:

  1. Shared domains created:
  2.  Context1:
    1. user12 email = → OK
  3. Context2:
    1. user22 email = → OK
    2. user23 email = → OK
  4. Context3:
    1. user31 email = → OK
    2. user32 email = → OK
    3. user33 email = → OK

You can still add Standard Domains into a Context, but the Shared Domains can be used in every Context.

Still not sufficient to achieve what you need? Let us look for the Explicit Domains.

Explicit Domain

What is true for Shared Domains is also true for Explicit Domains. They have to be created, before you create the first Context that shall use that Domain. And also for Explicit Domains, there is a specific REST API to allow that.


Create an Explicit Domain via REST API

API Documentation for Explicit-Domains

After that you continue as above with creating a Context and Users.

As mentioned earlier, the use case we currently see the most is for companies with several legal entities, that want to use a joined domain for their Email traffic, but there might be other use cases. Creating an Explicit Domain means, that you can use the same domain across several contexts within your Sub-admin Level. For this, you have to explicitly allow the use of that domain for more than one Context. Means this is an additional layer of security to avoid misuse if there is a need to share domains between your customers.

And again, here is a small illustration of what this means for your provisioning:

  1. Explicit domain created:
  2. Context allow to use context1, context2
  3.  Context1:
    1. user11 email =  → OK
    2. user12 email = → OK
  4. Context2:
    1. user23 email = → OK
  5. Context3:
    1. user31 email = → fail

Here stops, what OX Cloud allows to do with domains, but obviously there is more to do, that Emails can reach the OX Cloud system.

MX Configuration



<domain.tld> <TTL> MX 10


<domain.tld> <TTL> MX 10 mx001.domain.tld

mx001.domain.tld <TTL> IN CNAME

MX hosts for the OX Cloud EU default brand (

MX hosts for the OX Cloud US default brand (

As part of the onboarding process in case of a whitelabel agreement in OX the access point for configuring the corresponding customer MX DNS records are provided.


Brand : brand1

MX Hosts:

So for each domain created in the platform the customer has to set the corresponding MX records:

<domain.tld> MX 10
<domain.tld> MX 10
<domain.tld> MX 10
<domain.tld> MX 10