Releezme Integration Introduction

Introduction

Definitions 

  • Locker user: a user who interacts with via badge, Releezme app, or API integration for their They do not have a username/password to login to the Releezme portal.
  • System user: a user who has a username/password to login to the Releezme portal. Note: the Releezme portal can also use customer SSO for
  • API system user: a “service” user who has a username/password to login to the System API or SCIM API via the identity
  • Note: System and API system users are initially created by Locker users can be created by the customer via configuration website, import or SCIM API.

Basics 

  • The SCIM API is a REST based API, which means that is uses standard HTTP operations such as GET, PUT, POST and
    • With these operations it is possible to do create, read, update and delete (CRUD) of
  • The resource supported by Releezme are:
    • User, which represents the locker user in
    • Group, which represents the user group in
  • Examples:
    • GET /api/users which retrieves retrieve all users.
    • POST /api/users with a JSON content will create a new
    • GET /api/groups/42d7cfdf-73a0-45e0-b796-234a88625f87 which retrieves a specific

 

User Entity Example 

 User resource attributes

  • Releezme supports a subset of SCIM attributes:
    • Username: customer supplied unique
    • Name: given name and family
    • Active
    • Emails: only 1 email address is
    • Groups: zero or more groups can be set on the
  • Releezme adds a custom attribute for badges, which only has a value and display

Id/username 

  • “id” property in a user entity is filled by Releezme with a unique
  • “username” property in a user entity is given to Releezme by the client and must be a unique

Id/username approaches 

  • SCIM only allows PUT/DELETE/PATCH calls by using the “id” property and not the username. So there are two approaches for this:
    • Client ensures that they also know the “id” of the users within Releezme, by storing it locally when creating users or by retrieving the users in bulk.
    • Client retrieves the user from Releezme by using the GET /users call with a username This will return the single user entity if it exists in Releezme.

Domain Model 

  • A company consists of one or more locations and each location has one or more sections. And finally each section contains locker banks with one or more
  • A locker user is part of zero or more user
  • Access for users to (specific lockers) is controlled by a link between a specific user group and a locker

User groups 

  • A user should normally be put into a user group, since without it, the user has no rights to a
  • Configuring user groups is not trivial, therefore Releezme does not allow creation, deletion or modifications to user groups via the
  • When retrieving user groups, the list of users in the group is never returned.

Supported Operations – Discovery 

  • SCIM defines several end-points which are used for discovery of features and data
    • Service provider configuration: documents the features supported by a
    • Schemas: documents the schemas used for user and group
    • Resource Types: documents the resource types supported by the

Supported Operations – Resources 

  • User resources:
    • GET: retrieve a single user or all users (paged)
    • DELETE: delete a single
    • POST: Add a new user
    • PUT: Update an existing user
    • PATCH: Update one or more attributes from a user by using a sequence of add, remove or replace values.
  • Group resources:
    • GET: retrieve a single group or all groups (paged)
    • Note that Groups cannot be created, updated or

Swagger Support 

  • Integration API Server supports swagger:

Locker User Transfer

Locker User Transfer (2) 

  1. Customer server logs in to the Releezme Identity Server through OAuth 0 with a client specific client id/secret, and a company specific API system user with a username/password.
    • Note: one client server can access multiple company through additional company specific API system
  2. Customer server communicates with customer specific locker user data source
  3. Customer server synchronizes locker users with Releezme:
  4. Create new locker users in Releezme when create in their
  5. Read locker user users in Releezme and check if they in their source. (note: possible action could be to delete “unknown” Releezme locker users, or just some other action).
  6. Update locker users in Releezme when changed in their
  7. Delete locker users in Releezme when no longer present in their

Authentication 

  • Authentication of the caller of the System API is handled via OAuth 2.0 with a resource owner password See RZM_191.
  • Flow uses a password grant and a refresh
  • A client id and secret identify the client server as a
  • An API specific system user identifies the company to which the client has access
  • Note that some third-party servers handle multiple companies in Releezme while using the same client id and

Authentication – Flow

Authentication – Flow (2)

  • Client logs into the identity server with username/password.
  • Identity Server returns access token and refresh token
  • Client uses access token to communicate with the System API/SCIM API server. After 1 hour, the access token expires and API’s return
  • Client users refresh token to get a new access token and refresh
  • Client uses access token to communicate with the System API/SCIM API server. After 1 hour, the access token expires and API’s return 401.
  • After 30 days the refresh token expires and cannot be used anymore on the identity The client must then login with username/password again.

Document References 

Next Steps

  • Customer should supply the following:
    • Email address of the SCIM API system user. Normally this should be a service account. An email will be send there to setup the password. Note: this user does not have access to the
    • Mobile phone number to send the client secret
    • Additional email addresses for system users with access to the Releezme website. Each user will get a signup
  • Vecos will then:
    • Create integration company in Releezme’s integration
    • Create the SCIM API system user
    • Create the client id and secret. Id is sent via email. Secret via text

Finalizing the integration

  • During integration, support will be given by the Vecos integration engineer if
  • Once the customer is finished with it’s implementation, then:
    • Do a realistic test run of you
    • Send the timestamps (UTC) of the test run and a summary of the actions to the integration
  • After previous step, the integration engineer verifies the results and checks if everything is correct.
  • If so, then access to production is granted (note that everything must check out contractually also).
  • If not, then feedback is given and
Back to Top