Jump to content

Community

Developer Documentation

IPS Connect API

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


×
×
  • Create New...