Adding a Tenant

The goal of multitenancy is to maximize resource sharing across multiple users (while hiding the fact that these users are on the same server) and to ensure optimal performance. You can add a tenant using the CLI tool, REST API or the PPaaS Console, allowing tenants to maintain separate domains for their institutions as shown below:

Adding a tenant via the CLI

Overview

CLI command	add-tenant
Description	Add a new tenant.
Command format	add-tenant -u <USERNAME> -f <FIRST_NAME> -l <LAST_NAME> -p <PASSWORD> -d <DOMAIN_NAME> -e <EMAIL>

Parameter definition

Short option	Long option	Description	Required	Example value
-u	`--username`	Username given to the Tenant	Yes	admin
-f	`--first-name`	Tenant's first name	Yes	frank
-l	`--last-name`	Tenant's last name	Yes	Myers
-p	`--password`	Tenant's password	Yes	admin123
-d	`--domain-name`	Tenant's domain name	Yes	frank.com
-e	`--email`	Tenant's email address	Yes	[email protected]

Example

Add a tenant with the username: admin, name: Frank Myers, password: admin123, tenant domain: frank.com and email: [email protected].

add-tenant -u admin -f Frank -l Myers -p admin123 -d frank.com -e [email protected]

Sample output

Tenant added successfully: frank.com

Adding a tenant via the REST API

Overview

Description	Add a new tenant.
Resource Path	`/tenants`
HTTP Method	`POST`
Request/Response Format	`application/json`
Command format	curl -X POST -H "Content-Type: application/json" -d @'<JSON_PAYLOAD>' -k -v -u <USERNAME>:<PASSWORD> https://<PRIVATE_PAAS_HOST>:<PRIVATE_PAAS_HTTPS_PORT>/api/tenants The path to the JSON file that defines the tenant needs to be defined as the `<JSON_PAYLOAD>` value. By default, `<USERNAME>:<PASSWORD>` is `admin:admin.` By default, `<PRIVATE_PAAS_HOST>` is `localhost.` However, if you are using a public IP, the respective IP address or domain needs to be specified. By default, `<PRIVATE_PAAS_HTTPS_PORT>` has been set to 9443. However, if the port offset has been incremented by `n`, the default port value needs to be incremented by `n`.

Example

Add the tenant defined in the tenant.json file.

curl -X POST -H "Content-Type: application/json" -d @'tenant.json' -k -v -u admin:admin https://localhost:9443/api/tenants

Sample output

> POST /api/tenants HTTP/1.1
> Host: localhost:9443
> Authorization: Basic YWRtaW46YWRtaW4=
> User-Agent: curl/7.43.0
> Accept: */*
> Content-Type: application/json
> Content-Length: 169
> 
< HTTP/1.1 201 Created
< Date: Wed, 14 Oct 2015 06:40:13 GMT
< Location: https://localhost:9443/api/tenants/frank.com
< Content-Type: application/json
< Transfer-Encoding: chunked
< Server: WSO2 Carbon Server
< 
{"status":"success","message":"Tenant added successfully: [tenant] frank.com"}

You will come across the following HTTP status codes while adding a tenant:

HTTP status code

201, 400, 409, 500

See the descriptions of the HTTP status codes here.

Location header URL

https://<PRIVATE_PAAS_HOST>:<PRIVATE_PAAS_HTTPS_PORT>/api/tenants/<TENANT_DOMAIN>

Adding a tenant via the PPaaS Console

Follow the instructions below to add a tenant:

Only users who belong to the Tenant Admin user role will be allowed to add tenants in PPaaS.

Click Users on the home page.
Click Manage Tenants.
Click ADD TENANT.
Enter the required details. For property definitions, see Tenant property definitions.
Click SAVE TENANT.

Sample tenant JSON

{
  "admin": "admin",
  "firstName": "Frank",
  "lastName": "Myers",
  "adminPassword": "admin123",
  "tenantDomain": "frank.com",
  "email": "[email protected]",
  "active": "true"
}

When multitenancy is used, certain tenants can sometimes become inactive for a long period of time. By default, if the inactive period is 30 minutes, the tenant is unloaded from the server memory. This requires the tenant to log in again before sending requests to the server.

If required, you can change the default time allowed for tenant inactiveness by adding the -Dtenant.idle.time=<time_in_minutes> java property to the product startup script ( ./wso2server.sh file for Linux and wso2server.bat for Windows) as shown below:

JAVA_OPTS \
    -Dtenant.idle.time=30 \