- URL:
- https://<root>/joinSite
- Methods:
GET- Version Introduced:
- 10.4
Access requirements
Required privileges
The Portal Administrator API requires privilege-based access. An administrator must be assigned a specific user privilege, or role, to access any given endpoint. Listed below are the user privileges or roles an administrator can be assigned that provides access to this endpoint. If multiple privileges are listed, only one needs to be assigned to gain access.
Tokens
This API requires token-based authentication. A token is automatically generated for administrators who sign in to the Portal Administrator API directory's HTML interface. Tokens generated in this way are stored for the entirety of the session.
Those accessing the API directory outside of the HTML interface will need to acquire a session token from the generate operation in the Portal Directory API. For security reasons, all POST requests made to the Portal Administrator API must include a token in the request body.
Description
The join operation performs the following tasks when invoked:
- Registers a machine to an existing site (active machine)
- Creates a snapshot of the database of the active machine
- Updates the token shared key
- Updates Web Adaptor configurations
- Sets up replication to keep the database of both machines in sync
You must provide an account with administrative privileges to the site for the operation to be successful. When an attempt is made to join a site, the site validates the administrative credentials of the user invoking the operation. Once the administrative credentials are validated, the site returns connection information about its configuration store back to the portal machine. The portal machine then uses the connection information to work with the configuration store.
The operation is time-consuming as the database is configured on the machine and all configurations are applied from the active machine. After the operation is complete, the web server that hosts the API will be restarted.
Request parameters
| Parameter | Details |
|---|---|
| The admin URL of the existing portal site to which a machine will be joined. Example |
| The username for the initial administrator account of the existing portal site. Example |
| The password for the initial administrator account of the existing portal site. Example |
| The response format. The default response format is Values: |
Example usage
The following is a sample request for the join operation:
https://organization.example.com/<context>/portaladmin/joinSite?machineAdminUrl=https://portalhost.example.com:7443&username=admin&password=admin.secret&f=jsonJSON Response example
{
"status": "success",
"recheckAfterSecs": 10
}