User Management

Using the 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

API Version

API v4 is highly recommended.

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://{{subdomain}}.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://{{subdomain}}.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.

Creating Users

API Version

API v3 must be used.

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://{{subdomain}}.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"
  }'

External ID

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

API Version

API v3 must be used.

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://{{subdomain}}.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

API Version

API v3 must be used.

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://{{subdomain}}.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

API Version

API v3 must be used.

irreversible action

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://{{subdomain}}.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 our 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.