Skip to main content

User Management

Using the REST API, it is possible to integrate your master directory for user management with Showpad. This allows you to maintain a single source of truth in your master directory and manage Showpad user licenses from there.

In most cases, not every user in your master directory will be assigned to Showpad. Therefore, we advise creating a specific group that includes all Showpad entitled users. Any changes made to this group (i.e., adding, updating, or removing a user) should reflect in Showpad user management. This can be achieved by setting up a plugin that triggers an API call to Showpad whenever a user is added to, removed from, or updated in that user group.

Retrieving User Information

Getting user objects stored in Showpad is very straightforward. A GET request to https://{subdomain}.api.showpad.com/v4/users/{userId} or https://{subdomain}.api.showpad.com/v4/users can be done to retrieve a single user or a list of users, respectively.

See sample requests below:

# Getting a single user
curl --request GET \
--url https://customer.api.showpad.com/v4/users/c143c05d12c1433ba1358c7eb2e07c75 \
--header 'Authorization: Bearer MyApiToken' \
--header 'Content-Type: application/json'
# Getting a list of users
curl --request GET \
--url https://customer.api.showpad.com/v4/users \
--header 'Authorization: Bearer MyApiToken' \
--header 'Content-Type: application/json'

Check out the API Specification for more information regarding the API.

caution

While Showpad API v3 (deprecated) for retrieving user objects still works, it is strongly advised to use v4 instead.

Creating Users

note

Showpad API v3 is specifically used for this section. Showpad API v4 is not yet available at this time.

To add a user to Showpad, execute a POST request to https://{subdomain}.showpad.biz/api/v3/users.json (see also its API specification here). For a full overview of all data that can be passed on in the request body (e.g. license types, user roles, etc.), please refer to the API Specification.

See the sample request below:

curl --request POST \
--url https://customer.showpad.biz/api/v3/users.json \
--header 'Authorization: Bearer MyApiToken' \
--header 'Content-Type: application/json' \
--data '{
"email": "bob.smith@showpad.com",
"firstName": "Bob",
"lastName": "Smith",
"userName": "bob.smith@showpad.com",
"isActive": true,
"language": "en",
"externalId": "customer-ab7320ec521e4783be92512b7e400eb7"
}'
note

External ID: The externalId is an optional attribute used when creating a user. This attribute is usually the ID of the user in the customer's user directory. It 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.

info

A successful request will return a 201 Created status code. If there was a problem with the data provided, a 4xx Client Error status code will be returned. It will respond a 409 Conflict status code if the user entity submitted already exists.

Updating Users

note

Showpad API v3 is specifically used for this section. Showpad API v4 is not yet available at this time.

To update an existing user object, perform a PUT request to https://{subdomain}.showpad.biz/api/v3/users/{userId}.json, where userId is the User ID of the user object to be modified. Provide in the request body the attributes that need to be updated.

See the sample request below:

curl --request PUT \
--url https://customer.showpad.biz/api/v3/users/c143c05d12c1433ba1358c7eb2e07c75.json \
--header 'Authorization: Bearer MyApiToken' \
--header 'Content-Type: application/json' \
--data '{
"email": "bob.smith@showpad.com",
"firstName": "Bob",
"lastName": "Smith",
"userName": "bob.smith@showpad.com",
"isActive": true,
"language": "en"
}'

For a full overview of all data that can be passed on in the request body (e.g. license types, user roles, etc.), please refer to the API Specification.

Deactivating Users

note

Showpad API v3 is specifically used for this section. Showpad API v4 is not yet available at this time.

A user can be deactivated, using the same Update Users endpoint mentioned above, via PUT https://{subdomain}.showpad.biz/api/v3/users/{userId}.json, where {userId} is the User ID of the user object to be deactivated. The important attribute here is to set isActive to false.

See the sample request below:

curl --request PUT \
--url https://customer.showpad.biz/api/v3/users/c143c05d12c1433ba1358c7eb2e07c75.json \
--header 'Authorization: Bearer MyApiToken' \
--header 'Content-Type: application/json' \
--data '{ "isActive": false }'
note

To reactivate a user, perform the same request with isActive set to true.

Deleting Users

note

Showpad API v3 is specifically used for this section. Showpad API v4 is not yet available at this time.

warning

Deleting a user will completely remove the user and all its related data from Showpad. Therefore, it might be a good idea to perform the deletion when the user is permanently removed from the master user directory. Showpad suggests using deactivation for all other purposes instead.

Deleting a user is as easy as calling the DELETE https://{subdomain}.showpad.biz/api/v3/users/{userId}.json endpoint, where {userId} is the User ID of the user object to be deleted.

See the sample request below:

curl --request DELETE \
--url https://customer.showpad.biz/api/v3/users/c143c05d12c1433ba1358c7eb2e07c75.json \
--header 'Authorization: Bearer MyApiToken' \
--header 'Content-Type: application/json'

User Authentication

For security reasons, it is obviously not advised 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 (SSO) service. This allows users to log in with their corporate accounts. You can find more information about authenticating with Showpad's API here and implementing SSO in our Help Center.