User domains

Domains, routing and user visibility

The domain is the main framework or container of the users. Any user will be assigned to a domain. If is not specified, a default domain will be assigned.

By default (or based on contact configuration), the users of a domain have all the other users of the domain accessible to reach for presence and other information. Users from other domains are still reachable (you can dial and call them, using the username@domain unique identifier), but not directly accessible as other users from your own domain.

Any request on your application that involves an username without specify the domain will result on the resolution along your own domain.

Consider the following example. In the case that there are two users on the system: bob@quobis and bob@acme, if you as user of the quobis domain (alice@quobis) call to bob, it will be resolved as bob@quobis. You always have the option to call “the other Bob” if you dial directly to bob@acme.

Listing domains

An administrator user can retrieve the list of the domains on the system and the properties of it.

GET https://wac:8001/sapi/domains HTTP/1.1
Authorization: Bearer ec3fe973ea047b6fd38228eb9f9b9661cbb5b0fdeac01ff13af1ee
Content-Type: application/json

[
    {
        "id": "57877673e8f15d3472817349",
        "parent": null,
        "domain": "quobis",
        "origins": [
            null
        ],
        "enableAnonymous": false,
        "anonymousExpiration": 0,
        "anonymousCapabilities": [],
        "services": {
            "callalarms": [],
            "callcontrol": [],
            "chat": [],
            "contacts": [
                "wac",
                "static",
                "google"
            ],
            "datapipe": [],
            "filetransfer": [],
            "forms": [],
            "im": [],
            "ldap": [],
            "login": [],
            "meetings": [],
            "oauth2client": [],
            "presence": [],
            "remotelog": [],
            "usersettings": [
                "wac"
            ]
        }
    }
]

Where the following fields could be found:

id

UUID of the domain. To be used for other API operations.

parent

In case that there is a hierarchy of domains, this field will indicate the parent domain. Parent domain limitations will be extended to the the son domain.

domain

Name of the domain.

origins

Used to map the domain specified on the username login body request with the anonymous credential assigned.

enableAnonymous

Anonymous login enabling option.

anonymousExpiration

Time in milliseconds anonymous users are allowed to perform operations on the system before they will be requested to refresh the authentication.

anonymousCapabilities

List of capabilities of the anonymous users for this domain on the system. Check Users capabilities to expand information about this topic.

services

List of services available on the system. Some ones will include extra details in order to define the backends included on it.

Getting details about an specific domain

Once you get the UUID of the domain, you can retrieve the details of your domain. The READ access to the user’s domain details is granted for all users of the domain.

GET https://wac:8001/sapi/domains/57877673e8f15d3472817349 HTTP/1.1
Authorization: Bearer ec3fe973ea047b6fd38228eb9f9b9661cbb5b0fdeac01ff13af1ee
Content-Type: application/json

Creating a domain

On multi-tenant environments or based on the specific business needs, it could be convenient to have separated domains for different sets of users. This can be easily managed using the REST API to create the desired domains for the system.

POST https://wac:8001/sapi/domains HTTP/1.1
Authorization: Bearer ec3fe973ea047b6fd38228eb9f9b9661cbb5b0fdeac01ff13af1ee
Content-Type: application/json

{
    "domain": "demo.quobis.com",
    "parent": "quobis",
    "origins": ["demo.quobis.*"],
    "enableAnonymous": true,
    "services": {
        "login": [],
        "presence": [],
        "callcontrol": [],
        "contacts": ["wac", "static"]
    }
}

The previous example will create a new domain on the system that enables anonymous access and limit the services available to these users to the specified ones.

As you can understand it is specially interesting on use cases where anonymous users are involved. But also allows to create several domains where the users are not visible between them.

Update a domain

Typical use cases to update a domain is to grant a new service, remove it or to assign a new domain for the anonymous REFERRER header.

On this case, just use the PUT command with the UUID of the domain.

PUT https://wac:8001/sapi/domains/578895afe8f15d347281734f HTTP/1.1
Authorization: Bearer ec3fe973ea047b6fd38228eb9f9b9661cbb5b0fdeac01ff13af1ee
Content-Type: application/json

{
    "domain": "demo.quobis.com",
    "parent": "quobis",
    "origins": ["demo.quobis.com", "showcase.quobis.com"],
    "enableAnonymous": false,
    "services": {
        "login": [],
        "presence": [],
        "callcontrol": [],
        "contacts": ["wac", "static"]
    }
}