What's in it for you
As a company with 100+ users, it might be cumbersome to manage users in Showpad. You might come across the challenge to:
- Extract information from your own centralised user management environment and keep track of who has already been added
- Enter user details manually
- Keep track of user permissions in multiple locations (what if a user leaves that company or his permissions need to be revoked?)
As a result, a lot of time and effort is lost into user management. In this use-case, we'll discuss how you can integrate your own user management environment with Showpad using our API.
Key Features
We believe the 'truth' should only reside in one place. In the case of user management, this means that there should only be 1 master directory, which isn't only responsible for storing all user information but also for managing it. Integrating systems, such as Showpad, should only react to changes of state in this master directory. They should never be allowed to initiate changes of state, such as initiating a create, update or delete.
See this in detail
User Management Flow
In most cases, not every user will be assigned to Showpad. Therefore, we advise that all Showpad entitled users reside in a special Showpad group and that addition/updating/removal of a user within Showpad is determined by the addition/updating/removal of that user in that group. For example, if you add a user to the Showpad group, a user-created event could be thrown and be caught by a Showpad Plugin. This plugin could in turn make a Showpad API call to create the user.
Creation
The creation of one or more users happens via the POST /users.json API call. Specify the user details as an application/json array of key/value objects. When the users have been successfully created, you will receive a 201 response code. If there was a problem with the user details, you will receive a 40x response code. You will most likely get a 409 response code, signalling that the entity or entities you tried to submit were invalid.
Important to note is the externalId attribute used when creating a user. This attribute is usually the ID of the user in the customer's user directory and can be used to verify whether a user has already been added. More significantly, it can be used in order to map an authenticated user to a Showpad user via an Authentication mechanism like SAML (see below).
Updating
You can update a user via PUT /users/{id}.json, where {id} should be replaced with the user ID as retrieved from the API. You can use an application/json key/value array in the body to indicate which values should be updated.
Deactivating
You can deactivate a user via PUT /users/{id}.json, where {id} should be replaced with the user ID as retrieved from the API. You can use an application/json array with 'isActive" as key and 'false' as value. Make the same request but with the key set to 'true' to activate the user back again.
Deleting
You can easily delete a user via DELETE , where {id} should be replaced with the user ID as retrieved from the API. Deleting a user will completely remove the user and all its related data from Showpad. Therefore, it might be good to only delete a user when he is permanently removed from the master user directory. Use deactivation for all other purposes./users/{id}.json
Authentication
For security reasons, it is not advised (and hopefully not even possible) to send the user password when creating a new user via the Showpad API. When no password is entered, an invitation mail is sent to the user so the user can enter his own password privately.
Authentication can also work via a Single Sign On service. This allows users to log in with their corporate accounts. At the moment of writing, Showpad provides support for SAML 2.0 Identity providers.