API Documentation
Toggle TOC panel
<access-service>/api/v1/users

URL structure

1 https://access-service.xy-company.com/api/v1/users

Supported methods and overview

  • PUT - used to add the Safe Share administrator role to (or remove it from) a Covata user account * on the Covata Platform.
  • GET - used to retrieve a list of information associated with existing Safe Share administrator users on the Covata Platform.

Detailed description

This API endpoint serves a number of purposes:

  • Grants the Safe Share administrator role to (or remove it from) a Covata user account * on the Covata Platform. The Safe Share administrator role grants a user access to Safe Share Administration.
  • Retrieves a list of information associated with existing Safe Share administrators on the Covata Platform. The list of users returned in the response:
    • can be filtered according to users whose email address contains the string specified in the request,
    • can be sorted according to the user's email address, first name, last name or user ID and
    • is utilized on the Administrators page of Safe Share Administration.

* If a Covata user account is not already registered on the Covata Platform, then making this request automatically creates this user account.

Supported roles and conditions

This API endpoint supports the following Covata user roles (as described in the Safe Share Administrator's Guide):

  • Safe Share administrator - when this user is another Safe Share administrator user to the one whose account is being granted the Safe Share administrator role (or having it removed).

The Covata Platform's resources available to one of these Covata users (above) is determined by the access token submitted in the header of requests to this endpoint.

Required headers

The appropriate access token as the Bearer token:

  • Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...

The following header is required if the body of the request has a JSON object:

  • Content-Type: application/json

Required PUT-request parameters

The following required parameters must be sent in the body of the PUT request, as individual members of a JSON object:

  • email - The email address of the Covata user account with which to grant or remove the Safe Share administrator role.
  • admin - A boolean value of true to grant the Safe Share administrator role to the user (specified by email) or false to remove the Safe Share administrator role from this user.
    Example (PUT request parameters):
    {
    "email": "platform.administrator@xy-company.com",
    "admin": true
    }

Optional GET-request parameters

The following optional parameters can be sent in the URL of the GET request:

  • searchText - Any text substring used to filter for all Covata users with the Safe Share administrator role on the Covata Platform, where this text substring must match that of the user account's field specified in searchColumn below (or any of these fields). If this parameter is omitted, then no filtering is performed.
  • searchColumn - The user's field upon which the text substring (specified in searchText above) is used for filtering user accounts returned in the response. The fields available to this text searching include:

    • email - the email address associated with the Covata user.

    If this parameter is omitted, then no filtering is performed.
  • limit - An integer value from 0 to 100, representing the maximum number of items to be returned in the response from the Covata Platform, where an individual item is information about a Covata user with the Safe Share administrator role. If this parameter is omitted, then its value is 10 by default.
  • offset - A value representing the count order of all retrievable items (i.e. Covata users with the Safe Share administrator role) from the Covata Platform returned in the response. Calls to this API endpoint may amount to potentially large numbers of items being returned from the Covata Platform. Since the order of these items in the response could differ significantly, based on the values of the orderBy and sortBy parameters below, this offset parameter provides pagination for items returned in responses, allowing items to be retrieved from any count greater than 0 (i.e. the first item returned in a response). If this parameter is omitted, then its value is 0 by default.
  • orderBy - An enumeration (enum) value representing the order in which items (i.e. Covata users with the Safe Share administrator role) are returned in the response. This parameter orders items according to the value of the sortBy parameter specified below. Ordering items can be in either ascending alphanumeric order (by specifying the value ASC for this parameter) or descending order (by specifying the value DESC). If this parameter is omitted, then its value is ASC by default.
  • sortBy - A value representing the field (i.e. member) of a retrieved item by which items (i.e. Covata users with the Safe Share administrator role) returned in the response will be sorted. Valid field values for this parameter include:
    • email - the email address associated with the Covata user,
    • firstName - the first name (set by this user),
    • lastName - the last name (set by this user) and

    • userId - the ID of the Covata user account.

    If this parameter is omitted, then its value is email by default.
    Example (GET request):
    1 https://access-service.xy-company.com/api/v1/users?searchText=administrator&searchColumn=email

Returns

If the request succeeded, then an HTTP response status 200 OK is returned.

For successful requests only, a JSON-formatted response containing the following members is also returned:

  • items ( from GET requests only ) - An array containing information about all Covata user accounts on the Covata Platform which have the Safe Share administrator role, which have been filtered by any parameters submitted in the request. Each element of this array contains information about one of these user accounts (represented as an object containing the following members unless otherwise stated).
  • email - The email address of a Covata user account that either:
    • has the Safe Share administrator role (from a GET request to this endpoint), or
    • with which the Safe Share administrator role was granted or removed (from a PUT request).
  • firstName - The first name set by this user. This is the first name that appears on the Administrators page of Safe Share Administration, the Users page of Safe Share Organization Administration and/or the My Account feature of Covata Safe Share for Web.
  • lastName - The last name set by this user. Like the first name (above), this appears on the Administrators page of Safe Share Administration, the User page of Organization Administration and/or the My Account feature of Safe Share for Web.
  • mfaEnabled - A boolean value that indicates whether (true) or not (false) two-factor authentication has been set by this user on their own account, by another Safe Share administrator, or if this user is also a member of an organization, enforced for all members of the organization (by any Organization administrator of that organization).
  • systemAdmin - A boolean value that indicates whether (true) or not (false) this user's account has the Safe Share administrator role.
  • enabled - A boolean value that indicates whether (true) or not (false) this user's account has any role, such as the Safe Share administrator role. This value should be true.
  • accountNonLocked - A boolean value that indicates whether (false) or not (true) this user's account is locked. A Covata user account may become locked as a result of the user mistyping their password more than the maximum number of times configured (by themselves or another Safe Share administrator of their Covata Platform instance). The user themselves will need to unlock this account by following the instructions in their 'account lockout' notification (or by resetting their password via any of the options on the Covata Sign-in page).
  • numFailedLogins - The number of times this user failed to successfully sign in.
  • id ( from GET requests only ) - The ID value of this Covata user account.
  • count ( from GET requests only ) - The maximum number of items (i.e. Covata users with the Safe Share administrator role) that can be returned in the response.
  • offset ( from GET requests only ) - The value of the offset which had been used in the request to this endpoint.
    Example (response from a PUT request):
    {
    "email": "platform.administrator@xy-company.com",
    "firstName": null,
    "lastName": null,
    "mfaEnabled": false,
    "systemAdmin": true,
    "enabled": true,
    "accountNonLocked": true,
    "numFailedLogins": 0
    }

    Example (response from a GET request):
    {
    "items": [{
    "email": "another.administrator@xy-company.com",
    "firstName": "Another",
    "lastName": "Administrator",
    "mfaEnabled": false,
    "systemAdmin": true,
    "enabled": true,
    "accountNonLocked": true,
    "numFailedLogins": 0,
    "id": "747696349168070656"
    }, {
    "email": "platform.administrator@xy-company.com",
    "firstName": "Platform",
    "lastName": "Administrator",
    "mfaEnabled": false,
    "systemAdmin": true,
    "enabled": true,
    "accountNonLocked": true,
    "numFailedLogins": 0,
    "id": "757412808257589248"
    }],
    "count": "2",
    "offset": "0"
    }