Managing users

The Add-on Platform (AOP) provides a set of simple API calls to manage the creation, updating, and deactivation of user accounts in PaperCut cloud-native products.

Where possible we’re following the System for Cross-domain Identity Management (SCIM) specification to provide standardized integration of user account information.

The exception to the conventional SCIM workflow is the creation of a new user account in PaperCut via the API. In PaperCut Hive user accounts are not directly created. Instead users are sent an email invitation to accept and create their user account. This workflow does not accurately map the expectations of the SCIM model. See Provision user accounts below.

SCIM overview

The SCIM specification is designed to make managing user identities in cloud-based applications and services easier –Simple Cloud

SCIM 2.0 is released as RFC7643 and RFC7644.

While we encourage reading the above links to get familiar with the goals and function of the SCIM specification, the resulting APIs and payloads are fairly self explanatory.

There are some elements included as part of the SCIM spec, for example the schema element, which look as follows:

"schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
]

These fields are optional on inbound payloads, and you can safely ignore them on outbound payloads.

In short, if you are using a tool that already understands SCIM, it should have the data it needs to function. If you are writing your own code to consume the APIs, then these SCIM fields should not get in your way.

Provision user accounts

User accounts are not directly added in PaperCut’s cloud-native products with POST on the expected endpoint. Instead users are invited to complete a sign up process and user accounts are provisioned when the user completes the onboarding process.

For this reason, user account creation is initiated by the …/user-management/v1/invitations endpoint.

When this user resource is created, the PaperCut cloud-native platform sends an invitation email to complete the setup process. Make sure the email address is correct!

Note fir “Welcome Message”. When a user is invited to join a PaperCut Hive organization, the email can contain a custom welcome message, configured in the PaperCut Hive Administration Interface.

However, the configured default can be overridden via the optional invitation API field. You may want to prompt for custom text when the customer adds your add-on to the organization.

List a user with filter

To retrieve a single user profile, use the GET HTTP verb, with the correct query parameter, given the user name.

The query parameter must correspond to a username, email address, or external ID. This is distinct to the GET call (below) with a path parameter that must correspond to a user ID.

Retrieve a user profile

To retrieve a single user profile, use the GET HTTP verb, with the correct path parameter, given the user ID.

Update a user Account

To change a user account’s details, use the PUT HTTP verb.

Delete a user account

To delete a user account, use the DELETE HTTP verb.