This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.

Managing Tenants with APIs

This section guides you through invoking and working with the TenantManagementService and the operations you can work with in this service.

Invoking the admin service

TenantMgtAdminService is an admin service of the WSO2 Carbon platform. As admin services are secured to prevent anonymous invocations, you cannot view the WSDL of the admin service by default. Follow the steps below to view and invoke it:

  1. Set the <HideAdminServiceWSDLs> element to false in <IS_HOME>/repository/conf/carbon.xml file.

    <HideAdminServiceWSDLs>false</HideAdminServiceWSDLs>
  2. Restart the Identity Server.
  3. If you have started the server in default configurations, use the following URL in your browser to see the WSDL of the admin service: https://localhost:9443/services/TenantMgtAdminService?wsdl.

For more information on WSO2 admin services and how to invoke an admin service using either SoapUI or any other client program, see Calling Admin Services from Apps section in WSO2 Carbon documentation.

Operations included in the API

The following operations are available in the TenantManagement Service:

addTenant()
DescriptionAdds a new tenant.
Permission Level/permission/protected/manage/monitor/tenants
Input Parameters
ParameterTypeDescription
tenantInfoBeanTenantInfoBean Contains tenant related data
tenantInfoBean.tenantDomain StringThe domain name of the tenant
tenantInfoBean.active Boolean

True - activate the tenant

False- deactivate the tenant

tenantInfoBean.admin StringThe admin username
tenantInfoBean.adminPasswordStringThe admin password
tenantInfoBean.createdDateDateTimeThe date and time that the tenant was created
tenantInfoBean.emailStringThe email address of the tenant
tenantInfoBean.firstnameStringThe first name of the tenant
tenantInfoBean.lastnameStringThe last name of the tenant
tenantInfoBean.originatedService String-
tenantInfoBean.successKeyString-
tenantInfoBean.tenantDomainStringThe tenant domain
tenantInfoBean.tenantIdIntThe tenant ID
tenantInfoBean.usagePlanString-
Request
 Click here to see the request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://services.mgt.tenant.carbon.wso2.org" xmlns:xsd="http://beans.common.stratos.carbon.wso2.org/xsd">
    <soapenv:Header/>
    <soapenv:Body>
        <ser:addSkeletonTenant>
            <!­­Optional:­­>
            <ser:tenantInfoBean>
                <!­­Optional:­­>
                <xsd:active>true</xsd:active>
                <!­­Optional:­­>
                <xsd:admin>testuser</xsd:admin>
                <!­­Optional:­­>
                <xsd:adminPassword>testpw</xsd:adminPassword>
                <!­­Optional:­­>
                <xsd:createdDate></xsd:createdDate>
                <!­­Optional:­­>
                <xsd:email>testuser@example.com</xsd:email>
                <!­­Optional:­­>
                <xsd:firstname>First</xsd:firstname>
                <!­­Optional:­­>
                <xsd:lastname>Last</xsd:lastname>
                <!­­Optional:­­>
                <xsd:originatedService></xsd:originatedService>
                <!­­Optional:­­>
                <xsd:successKey></xsd:successKey>
                <!­­Optional:­­>
                <xsd:tenantDomain>example.com</xsd:tenantDomain>
                <!­­Optional:­­>
                <xsd:tenantId></xsd:tenantId>
                <!­­Optional:­­>
                <xsd:usagePlan></xsd:usagePlan>
            </ser:tenantInfoBean>
        </ser:addSkeletonTenant>
    </soapenv:Body>
</soapenv:Envelope>             
Response

None

activateTenant()
DescriptionActivates an existing tenant.
Permission Level/permission/protected/manage/modify/tenants
Input Parameters
ParameterTypeDescription
tenantDomain StringThe domain name of the tenant
Request
 Click here to see the request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ser="http://services.mgt.tenant.carbon.wso2.org">
    <soapenv:Header/>
    <soapenv:Body>
        <ser:activateTenant>
            <!­­Optional:­­>
            <ser:tenantDomain>example.com</ser:tenantDomain>
        </ser:activateTenant>
    </soapenv:Body>
</soapenv:Envelope>              
Response
 Click here to see the response
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <ns:activateTenantResponse xmlns:ns="http://services.mgt.tenant.carbon.wso2.org">
            <ns:return xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema­instance" />
        </ns:activateTenantResponse>
    </soapenv:Body>
</soapenv:Envelope>
deactivateTenant()
DescriptionDeactivates an existing tenant.
Permission Level/permission/protected/manage/modify/tenants
Input Parameters
ParameterTypeDescription
tenantDomain StringThe domain name of the tenant
Request
 Click here to see the request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ser="http://services.mgt.tenant.carbon.wso2.org">
    <soapenv:Header/>
    <soapenv:Body>
        <ser:deactivateTenant>
            <!­­Optional:­­>
            <ser:tenantDomain>example.com</ser:tenantDomain>
        </ser:deactivateTenant>
    </soapenv:Body>
</soapenv:Envelope>               
Response
 Click here to see the response
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <ns:deactivateTenantResponse xmlns:ns="http://services.mgt.tenant.carbon.wso2.org">
            <ns:return xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema­instance" />
        </ns:deactivateTenantResponse>
    </soapenv:Body>
</soapenv:Envelope>
getTenant()
DescriptionRetrieves tenant details by domain name.
Permission Level/permission/protected/manage/monitor/tenants
Input Parameters
ParameterTypeDescription
tenantInfoBean.tenantDomain StringThe domain name of the tenant
Request
 Click here to see the request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ser="http://services.mgt.tenant.carbon.wso2.org">
    <soapenv:Header/>
    <soapenv:Body>
        <ser:getTenant>
            <!­­Optional:­­>
            <ser:tenantDomain>example.com</ser:tenantDomain>
        </ser:getTenant>
    </soapenv:Body>
</soapenv:Envelope>              
Response
 Click here to see the response
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <ns:getTenantResponse xmlns:ns="http://services.mgt.tenant.carbon.wso2.org">
            <ns:return xsi:type="ax2582:TenantInfoBean" xmlns:ax2584="http://beans.mgt.tenant.carbon.wso2.org/xsd" xmlns:ax2582="http://beans.common.stratos.carbon.wso2.org/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema­instance">
                <ax2582:active>true</ax2582:active>
                <ax2582:admin>test</ax2582:admin>
                <ax2582:adminPassword xsi:nil="true" />
                <ax2582:createdDate>2015­02­13T07:27:17.543+05:30</ax2582:createdDate>
                <ax2582:email>test@example.com</ax2582:email>
                <ax2582:firstname>Test</ax2582:firstname>
                <ax2582:lastname>User</ax2582:lastname>
                <ax2582:originatedService xsi:nil="true" />
                <ax2582:successKey xsi:nil="true" />
                <ax2582:tenantDomain>example.com</ax2582:tenantDomain>
                <ax2582:tenantId>1</ax2582:tenantId>
                <ax2582:usagePlan/>
            </ns:return>
        </ns:getTenantResponse>
    </soapenv:Body>
</soapenv:Envelope>
retrievePaginatedPartialSearchTenants()
DescriptionRetrieves the tenant information based on the partial search.
Permission Level /permission/protected/manage/monitor/tenants
Input Parameters
ParameterTypeDescription
tenantStringPartial tenant domain name
pageNumberIntPage number
Request
 Click here to see the request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://services.mgt.tenant.carbon.wso2.org">
    <soapenv:Header/>
    <soapenv:Body>
        <ser:retrievePaginatedPartialSearchTenants>
            <!­­Optional:­­>
            <ser:domain>.com</ser:domain>
            <!­­Optional:­­>
            <ser:pageNumber>1</ser:pageNumber>
        </ser:retrievePaginatedPartialSearchTenants>
    </soapenv:Body>
</soapenv:Envelope>             
Response
 Click here to see the response
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <ns:retrievePaginatedPartialSearchTenantsResponse xmlns:ns="http://services.mgt.tenant.carbon.wso2.org">
            <ns:return xsi:type="ax2584:PaginatedTenantInfoBean" xmlns:ax2584="http://beans.mgt.tenant.carbon.wso2.org/xsd" xmlns:ax2582="http://beans.common.stratos.carbon.wso2.org/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema­instance">
                <ax2584:numberOfPages>1</ax2584:numberOfPages>
                <ax2584:tenantInfoBeans xsi:type="ax2582:TenantInfoBean">
                    <ax2582:active>true</ax2582:active>
                    <ax2582:admin xsi:nil="true" />
                    <ax2582:adminPassword xsi:nil="true" />
                    <ax2582:createdDate>2015­02­13T07:27:17.543+05:30</ax2582:createdDate>
                    <ax2582:email>test@example.com</ax2582:email>
                    <ax2582:firstname xsi:nil="true" />
                    <ax2582:lastname xsi:nil="true" />
                    <ax2582:originatedService xsi:nil="true" />
                    <ax2582:successKey xsi:nil="true" />
                    <ax2582:tenantDomain>example.com</ax2582:tenantDomain>
                    <ax2582:tenantId>1</ax2582:tenantId>
                    <ax2582:usagePlan xsi:nil="true" />
                </ax2584:tenantInfoBeans>
            </ns:return>
        </ns:retrievePaginatedPartialSearchTenantsResponse>
    </soapenv:Body>
</soapenv:Envelope>
retrievePaginatedTenants()
DescriptionActivates an existing tenant.
Permission Level/permission/protected/manage/monitor/tenants
Input Parameters
ParameterTypeDescription
pageNumber IntPage number
Request
 Click here to see the request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ser="http://services.mgt.tenant.carbon.wso2.org">
    <soapenv:Header/>
    <soapenv:Body>
        <ser:retrievePaginatedTenants>
            <!­­Optional:­­>
            <ser:pageNumber>1</ser:pageNumber>
        </ser:retrievePaginatedTenants>
    </soapenv:Body>
</soapenv:Envelope>          
Response
 Click here to see the response
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <ns:retrievePaginatedTenantsResponse xmlns:ns="http://services.mgt.tenant.carbon.wso2.org">
            <ns:return xsi:type="ax2584:PaginatedTenantInfoBean" xmlns:ax2584="http://beans.mgt.tenant.carbon.wso2.org/xsd" xmlns:ax2582="http://beans.common.stratos.carbon.wso2.org/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema­instance">
                <ax2584:numberOfPages>1</ax2584:numberOfPages>
                <ax2584:tenantInfoBeans xsi:type="ax2582:TenantInfoBean">
                    <ax2582:active>true</ax2582:active>
                    <ax2582:admin xsi:nil="true" />
                    <ax2582:adminPassword xsi:nil="true" />
                    <ax2582:createdDate>2015­02­13T07:27:17.543+05:30</ax2582:createdDate>
                    <ax2582:email>test@example.com</ax2582:email>
                    <ax2582:firstname xsi:nil="true" />
                    <ax2582:lastname xsi:nil="true" />
                    <ax2582:originatedService xsi:nil="true" />
                    <ax2582:successKey xsi:nil="true" />
                    <ax2582:tenantDomain>example.com</ax2582:tenantDomain>
                    <ax2582:tenantId>1</ax2582:tenantId>
                    <ax2582:usagePlan xsi:nil="true" />
                </ax2584:tenantInfoBeans>
            </ns:return>
        </ns:retrievePaginatedTenantsResponse>
    </soapenv:Body>
</soapenv:Envelope>
retrievePartialSearchTenants()
DescriptionRetrieves all tenants that contain the specified part of the domain name (e.g., All tenant domains with ‘.com’)
Permission Level/permission/protected/manage/monitor/tenants
Input Parameters
ParameterTypeDescription
domainStringPartial tenant domain name
Request
 Click here to see the request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://services.mgt.tenant.carbon.wso2.org">
    <soapenv:Header/>
    <soapenv:Body>
        <ser:retrievePartialSearchTenants>
            <!­­Optional:­­>
            <ser:domain>.com</ser:domain>
        </ser:retrievePartialSearchTenants>
    </soapenv:Body>
</soapenv:Envelope>             
Response
 Click here to see the response
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <ns:retrievePartialSearchTenantsResponse xmlns:ns="http://services.mgt.tenant.carbon.wso2.org" xmlns:ax2584="http://beans.mgt.tenant.carbon.wso2.org/xsd" xmlns:ax2582="http://beans.common.stratos.carbon.wso2.org/xsd">
            <ns:return xsi:type="ax2582:TenantInfoBean" xmlns:xsi="http://www.w3.org/2001/XMLSchema­instance">
                <ax2582:active>true</ax2582:active>
                <ax2582:admin xsi:nil="true" />
                <ax2582:adminPassword xsi:nil="true" />
                <ax2582:createdDate>2015­02­13T07:27:17.543+05:30</ax2582:createdDate>
                <ax2582:email>test@example.com</ax2582:email>
                <ax2582:firstname xsi:nil="true" />
                <ax2582:lastname xsi:nil="true" />
                <ax2582:originatedService xsi:nil="true" />
                <ax2582:successKey xsi:nil="true" />
                <ax2582:tenantDomain>example.com</ax2582:tenantDomain>
                <ax2582:tenantId>1</ax2582:tenantId>
                <ax2582:usagePlan xsi:nil="true" />
            </ns:return>
        </ns:retrievePartialSearchTenantsResponse>
    </soapenv:Body>
</soapenv:Envelope>
retrieveTenants()
DescriptionRetrieves all tenants.
Permission Level/permission/protected/manage/monitor/tenants
Input Parameters

None

Request
 Click here to see the request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ser="http://services.mgt.tenant.carbon.wso2.org">
    <soapenv:Header/>
    <soapenv:Body>
        <ser:retrieveTenants/>
    </soapenv:Body>
</soapenv:Envelope>             
Response
 Click here to see the response
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <ns:retrieveTenantsResponse xmlns:ns="http://services.mgt.tenant.carbon.wso2.org" xmlns:ax2584="http://beans.mgt.tenant.carbon.wso2.org/xsd" xmlns:ax2582="http://beans.common.stratos.carbon.wso2.org/xsd">
            <ns:return xsi:type="ax2582:TenantInfoBean" xmlns:xsi="http://www.w3.org/2001/XMLSchema­instance">
                <ax2582:active>true</ax2582:active>
                <ax2582:admin xsi:nil="true" />
                <ax2582:adminPassword xsi:nil="true" />
                <ax2582:createdDate>2015­02­13T07:27:17.543+05:30</ax2582:createdDate>
                <ax2582:email>test@example.com</ax2582:email>
                <ax2582:firstname xsi:nil="true" />
                <ax2582:lastname xsi:nil="true" />
                <ax2582:originatedService xsi:nil="true" />
                <ax2582:successKey xsi:nil="true" />
                <ax2582:tenantDomain>example.com</ax2582:tenantDomain>
                <ax2582:tenantId>1</ax2582:tenantId>
                <ax2582:usagePlan xsi:nil="true" />
            </ns:return>
        </ns:retrieveTenantsResponse>
    </soapenv:Body>
</soapenv:Envelope>
updateTenant()
DescriptionUpdates the tenant details based on the specified tenantId. To update the password, the respective admin name should be included.
Permission Level /permission/protected/manage/modify/tenants
Input Parameters
ParameterTypeDescription
tenantInfoBeanTenantInfoBean Contains tenant related data
tenantInfoBean.tenantDomain StringThe domain name of the tenant
tenantInfoBean.active Boolean

True - activate the tenant

False- deactivate the tenant

tenantInfoBean.admin StringThe admin username
tenantInfoBean.adminPasswordStringThe admin password
tenantInfoBean.createdDateDateTimeThe date and time that the tenant was created
tenantInfoBean.emailStringThe email address of the tenant
tenantInfoBean.firstnameStringThe first name of the tenant
tenantInfoBean.lastnameStringThe last name of the tenant
tenantInfoBean.originatedService String-
tenantInfoBean.successKeyString-
tenantInfoBean.tenantDomainStringThe tenant domain
tenantInfoBean.tenantIdIntThe tenant ID
tenantInfoBean.usagePlanString-
Request
 Click here to see the request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ser="http://services.mgt.tenant.carbon.wso2.org" xmlns:xsd="http://beans.common.stratos.carbon.wso2.org/xsd">
    <soapenv:Header/>
    <soapenv:Body>
        <ser:updateTenant>
            <!­­Optional:­­>
            <ser:tenantInfoBean>
                <!­­Optional:­­>
                <xsd:active>true</xsd:active>
                <!­­Optional:­­>
                <xsd:admin>test</xsd:admin>
                <!­­Optional:­­>
                <xsd:adminPassword>testpw</xsd:adminPassword>
                <!­­Optional:­­>
                <xsd:createdDate></xsd:createdDate>
                <!­­Optional:­­>
                <xsd:email>testuser@example.com</xsd:email>
                <!­­Optional:­­>
                <xsd:firstname>test</xsd:firstname>
                <!­­Optional:­­>
                <xsd:lastname>user</xsd:lastname>
                <!­­Optional:­­>
                <xsd:originatedService></xsd:originatedService>
                <!­­Optional:­­>
                <xsd:successKey></xsd:successKey>
                <!­­Optional:­­>
                <xsd:tenantDomain>example.com</xsd:tenantDomain>
                <!­­Optional:­­>
                <xsd:tenantId>1</xsd:tenantId>
                <!­­Optional:­­>
                <xsd:usagePlan></xsd:usagePlan>
            </ser:tenantInfoBean>
        </ser:updateTenant>
    </soapenv:Body>
</soapenv:Envelope>            
Response
 Click here to see the response
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <ns:updateTenantResponse xmlns:ns="http://services.mgt.tenant.carbon.wso2.org">
            <ns:return xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema­instance" />
        </ns:updateTenantResponse>
    </soapenv:Body>
</soapenv:Envelope>