Master IPS Connect applications will need to accept the following requests and respond accordingly with the response parameters outlined for each request. It will also need to propagate the requests to each slave in its network, differentiating the requests with a "slaveCall=1" request parameter. Slave IPS Connect applications will need to call the following API endpoints against the master IPS Connect installation it is communicating with, and additionally accept the same API request calls (differentiated with a slaveCall=1) in order to accept and make changes to the local database when changes are made at a remote website in the Connect network.
The following GET request parameters will always be included:
- do: This is the action to perform, as outlined below.
- key: This is the secure key and should be validated to ensure it matches the secure key supplied to the slave application.
- url: This is the URL to the slave application.
Other GET request parameters will be sent and will vary depending upon the request. All requests from the master installation to slave installations will also include
- slaveCall: Always set to '1', this allows the slave application to know that the request is coming from a master application and is intended to result in the local database being updated.
Important note: If 'id' is passed in the request to make a change to a specific user account, the 'key' value will be an MD5 hash of the master application's key concatenated with the id. For instance:
$key = md5( $masterKey . $id );
All responses will include a 'status' key in the JSON response. Some responses may include additional information. You should verify the 'status' response is SUCCESS to ensure the action completed successfully. Invalid requests will have a status of INVALID_ACTION. Slave applications that no longer wish to be a part of the network (i.e. if IPS Connect is disabled at this installation) should respond with a status of DISABLED.
Example:
print json_encode( array( 'status' => 'SUCCESS' ) ); exit;
Method: verifySettings
This method is intended to allow a slave application to verify the settings of the master (i.e. when the master key is first provided) and to "register" with the master installation. This allows the master installation to propagate requests to slave applications later.
GET parameters:
- ourKey: [Required] This is a unique key associated with the slave
Response status codes:
- SUCCESS
Response parameters: None
Method: fetchSalt
Call this method in order to fetch a user's password salt - necessary for allowing the local application to hash the user's credentials properly before sending them to the master.
GET parameters:
- idType: [Required] What type of ID is being passed (a value of 1 indicates the id is a display name, a value of 2 indicates the id is an email address and a value of 3 indicates the value could be either a display name OR an email address)
- id: [Required] The user ID
Response status codes:
- SUCCESS
- REQUEST_MISSING_DATA: This indicates either idType or id was not provided
- ACCOUNT_NOT_FOUND: No account was found based on the supplied value
Response parameters:
- pass_salt: The salt applied to the password when hashing it
Method: login
This method authenticates a user and logs the user into all applications on the IPS Connect network.
GET parameters:
- idType: [Required] What type of ID is being passed (a value of 1 indicates the id is a display name, a value of 2 indicates the id is an email address and a value of 3 indicates the value could be either a display name OR an email address)
- id: [Required] The user ID
- password: [Required] The encrypted password
NOTE:
The 'password' parameter must be encrypted in the same manner as the IPS Community Suite. A request should first be sent to fetch the user's salt (see fetchSalt above), and then the password should be hashed in the following manner:
/* $password is the raw password and $salt is the salt returned from fetchSalt */ crypt( $password, '$2a$13$' . $salt );
$2a$13$ refers to the salt prefix and a pre-determined cost factor that should not be altered.
Response status codes:
- SUCCESS
- REQUEST_MISSING_DATA: This indicates either idType or id was not provided
- WRONG_AUTH: This indicates that the provided credentials could not be authenticated. This may mean that no account exists with the id provided or that the password is not valid.
Response parameters:
- connect_status: VALIDATING if the account is still validating or SUCCESS otherwise
- email: The member's email address
- name: The member's display name
- connect_id: The member's unique integer ID on the master installation
- connect_revalidate_url: If the member is VALIDATING, the URL that any slave application's should send the user to in order to complete their validation
Method: crossLogin
When a user logs in to a slave application successfully, they will be redirected to the crossLogin method of the master application in order to be logged in to it and all other slave applications on the network. This is necessary to work around cross-domain cookie restrictions. The master install will need to redirect the user to each slave's crossLogin method, and will also need to log the user in to the master application, before returning the user to the originating URL (the original slave application the user logged in to).
GET parameters:
- id: The member's unique integer ID on the master installation
- returnTo: a URL to return the user to once the user has been logged on.
NOTE:
When the master application redirects the user to slave applications to log the user on, the returnTo URL should be compared to the url parameter in order to ensure the user is not sent to the originating slave. When sending the user to another slave in the network, the returnTo parameter should be set to the master URL. Further, the master application should set a 'slaveCall' parameter to 1 when calling slave applications to prevent them from performing extra work (this allows slave applications to know that the request is from the master and to perform specific duties).
Response status codes: None, the user will be redirected to the returnTo URL
Response parameters: None
Method: logout
API calls to the logout method are designed to log the user out of the master application as well as all of the slave installations.
GET parameters:
- returnTo: The URL to return the user to once they have been logged out
- id: The member's unique integer ID on the master installation
NOTE:
Much like the crossLogin method, the logout method should redirect the user to all slave applications to log the user out and then log the user out of the master application before returning the user to the originating installation. slaveCall is passed in the URL when the master calls slave applications to differentiate requests between master and slave applications.
Response status codes: None, the user will be redirected to the returnTo URL
Response parameters: None
Method: register
Register the user on all installations in the Connect network
GET parameters:
- name: The member's name
- email: The member's email address
- pass_hash: The member's password hash
- pass_salt: The member's password salt
- revalidateUrl: The URL to send the user to if they are validating and attempt to login to any other site in the connect network
NOTE:
The 'pass_hash' parameter must be encrypted in the same manner as the IPS Community Suite. The password should be hashed in the following manner:
/* $password is the raw password and $salt is the salt returned from fetchSalt */ crypt( $password, '$2a$13$' . $salt );
Response status codes:
- SUCCESS
- REQUEST_MISSING_DATA: This indicates email, name, pass_salt or pass_hash was not passed
Response parameters:
- connect_id: The member's unique integer ID on the connect network
Method: validate
Call this method in order to mark a user's account as validated. If a user account is marked as awaiting validation and the user validates, this should be called to ensure the user account is marked as validated across the entire network.
GET parameters:
- id: [Required] The unique user ID of the user account
Response status codes:
- SUCCESS
Response parameters: None
Method: delete
Call this method in order to delete a user account. THERE IS NO UNDOING THIS ACTION.
GET parameters:
- id: [Required] The unique user ID of the user account
Response status codes:
- SUCCESS
Response parameters: None
Method: ban
Call this method in order to ban or unban a user account
GET parameters:
- id: [Required] The unique user ID of the user account
- status: [Required] A value of 1 will ban the user account while a value of 0 will unban the user account
Response status codes:
- SUCCESS
Response parameters: None
Method: merge
Call this method in order to merge two distinct user accounts into one. THERE IS NO UNDOING THIS ACTION.
GET parameters:
- id: [Required] The unique user ID of the account you wish to keep
- remote: [Required] The unique user ID of the account you wish to remove
Response status codes:
- SUCCESS
Response parameters: None
Method: checkEmail
Call this method in order to check if an email exists at the master application. This can be useful to prevent a user who has already registered elsewhere on the Connect network from registering again on a local site, when they should instead login.
GET parameters:
- email: [Required] The email address to check
Response status codes:
- SUCCESS
Response parameters:
- used: 1 if the email address is in use or 0 if not
Method: checkName
Call this method in order to check if a username exists at the master application. This can be useful to prevent a user who has already registered elsewhere on the Connect network from registering again on a local site, when they should instead login. It is not necessary to enforce uniqueness of display names in your application if your application has a need to allow multiple user accounts with the same display name to exist, however you should never allow logging in by 'display name' if this is the case.
GET parameters:
- name: [Required] The name to check
Response status codes:
- SUCCESS
Response parameters:
- used: 1 if the name is in use or 0 if not
Method: changeEmail
This method is called when an existing user's email address should be updated to a new value.
GET parameters:
- email: [Required] The new email address to use
- id: [Required] Unique user ID provided by the master application to a previous login or registration call
Response status codes:
- SUCCESS
- REQUEST_MISSING_DATA: The new email address to use was not supplied
- EMAIL_IN_USE: The new email address is already being used by another account
Response parameters: None
Method: changePassword
This method is called when a user has updated their password
GET parameters:
- pass_salt: [Required] Password salt
- pass_hash: [Required] Password hash
- id: [Required] Unique user ID provided by the master application to a previous login or registration call
NOTE:
The 'pass_hash' parameter must be encrypted in the same manner as the IPS Community Suite. The password should be hashed in the following manner:
/* $password is the raw password and $salt is the salt to be passed with pass_salt */ crypt( $password, '$2a$13$' . $salt );
Response status codes:
- SUCCESS
- REQUEST_MISSING_DATA: The password salt or password hash was not supplied
Response parameters: None
Method: changeName
This method is called when an existing user has changed their display name at a local installation
TIP: You can disable username changes from propagating to all sites within a network. This can be useful when you want to share login credentials amongst all of your sites, but want user accounts to otherwise appear to be separate. To do this with the Community Suite you must create a file called constants.php in your root directory (where index.php is), or edit the existing one if it already exists. Paste the following code into the constants.php file (if you are editing an existing file, omit the opening <?php tag):
<?php define( 'CONNECT_NOSYNC_NAMES', TRUE );
If this is done on a slave IPS Community Suite application, that slave (only) will ignore username change requests and will not send username changes to the master application. If the above constant is set on a master IPS Community Suite application, username change requests will not be propagated to anyslaves in the network. You should carefully consider your intentions if you decide to make the change above.
GET parameters:
- name: [Required] The new name to use
- id: [Required] Unique user ID provided by the master application to a previous login or registration call
Response status codes:
- SUCCESS
- REQUEST_MISSING_DATA: The new name to use was not supplied
- USERNAME_IN_USE: The new name is already being used by another account
Response parameters: None
Report Document