This documentation is for WSO2 Private PaaS 4.1.0. View documentation for the latest release.
Adding a Tenant - WSO2 Private PaaS 4.1.0 - WSO2 Documentation
Skip to end of metadata
Go to start of metadata

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

CLI command
DescriptionAdd 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 optionLong optionDescriptionRequiredExample value


Username given to the TenantYesadmin


Tenant's first nameYesfrank


Tenant's last nameYesMyers


Tenant's passwordYesadmin123


Tenant's domain


Tenant's email addressYes[email protected]

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

add-tenant -u admin -f Frank -l Myers -p admin123 -d -e [email protected]
Sample output
Tenant added successfully:

Adding a tenant via the REST API

DescriptionAdd a new tenant.
Resource Path/tenants
Request/Response Formatapplication/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.

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/
< Content-Type: application/json
< Transfer-Encoding: chunked
< Server: WSO2 Carbon Server
{"status":"success","message":"Tenant added successfully: [tenant]"}

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


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.

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


Sample tenant JSON

  "admin": "admin",
  "firstName": "Frank",
  "lastName": "Myers",
  "adminPassword": "admin123",
  "tenantDomain": "",
  "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 ( ./ file for Linux and   wso2server.bat  for Windows) as shown below:


    -Dtenant.idle.time=30 \
  • No labels