<access-service>/api/v1/users/me

URL structure

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

Supported methods and overview

• GET - retrieves information about the Covata user whose access token is submitted in the request to this endpoint.
• PUT - modifies the account details of the Covata user whose access token is submitted in the request to this endpoint.

Note: The GET method takes no parameters.

Detailed description

This API endpoint serves a number of purposes:

• Retrieves information about the Covata user whose access token is submitted in the request to this endpoint.
• Modifies the account details of the Covata user whose access token is submitted in the request to this endpoint.
  Note: These account details can also be modified through the My Account feature of Safe Share for Web.

Supported roles

This API endpoint supports requests utilizing Covata user accounts with the following roles (as described in the Safe Share Administrator's and Organization Administrator's Guides):

• Originator
• Collaborator
• Ad hoc
• Safe Share administrator
• Organization administrator

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

Optional parameters

The following parameters can also be sent in the body of the PUT request, each as individual members of a JSON object:

• firstName - The first name to be set by the Covata user whose access token is submitted in the request to this endpoint. Omitting this value in the request clears this property's value to null ¹ .
• lastName - The last name to be set by this user. Omitting this value in the request clears this property's value to null ¹ .
• otherName - The other (e.g. middle) name to be set by this user. Omitting this value in the request clears this property's value to null ¹ .
• mobileNumber - The mobile number to be set by this user. This number must include the country calling code and plus (+) sign prefix - for example, +1 234 567 8910 for a US-based number. Omitting this value in the request clears this property's value to null ¹ .
• i18nPreferenceCode - The I18n Code (described in Managing internationalization in the Safe Share Administrator's Guide) representing the language and locale to be set by this user.
• homeOrganisationId - The ID of the organization (to be set by this user) as the user's home organization.
• mfaEnabled - A boolean value to be set by this user to activate (i.e. true) or deactivate (false) two-factor authentication on the user's account.
  Example (request):

  {  
    "firstName": "Alex",
    "lastName": "Originator",
    "otherName": "Jay",
    "mobileNumber": "+61 401 234 567",
    "i18nPreferenceCode": "en_gb"
  }

¹ If none of the parameters above are specified, then an empty JSON object must be passed in the body of the PUT request for the request to succeed:

• {}

Specifiying an empty JSON object like this clears the values for firstName, lastName, otherName and mobileNumber (above) to null.

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:

• externalUserId - .
• email - The email address of the Covata user account whose access token was submitted in the request to this endpoint.
• firstName - The first name set by this user, which is null if this value was omitted in a PUT request to this endpoint. 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, which is null if this value was omitted in a PUT request to this endpoint. 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.
• otherName - The other name (e.g. middle) set by this user, which is null if this value was omitted in a PUT request to this endpoint. This name appears on the My Account feature of Safe Share for Web.
• mobileNumber - The mobile number set by this user, which is null if this value was omitted in a PUT request to this endpoint. This number appears on the My Account feature of Safe Share for Web.
• mfaEnabled - A boolean value that indicates whether (true) or not (false) two-factor authentication has either been set by this user on their own account, or enforced for all members of the organization (by any Organization administrator of this organization).
• systemAdmin - A boolean value that indicates whether (true) or not (false) this user's account has the Safe Share administrator role.
• homeOrganisationId - The ID of the organization (set by this user) as their home organization.
• i18nPreferenceCode - The I18n Code (described in Managing internationalization in the Safe Share Administrator's Guide) representing the language and locale set by this user.
• notificationFrequency - An enumeration (enum) value representing the frequency with which this user receives an email notification about items being shared with them. Valid values include:
  • ITEM - An email notification is sent by the Covata Platform to this user each time an item is shared with the user. These notifications may be less frequent (resulting in a list/digest of items being sent) based on the Item shared notification frequency in minutes Notification properties setting in Safe Share Administration.
  • DAILY - An email notification (containing a digest of items shared with this user) is sent once per day each time at least one item is shared with the user during this period.
  • WEEKLY - An email notification (containing a digest of items shared with this user) is sent once per week each time at least one item is shared with the user during this period.
  • NONE - No notifications are sent when items are shared.
• lastLoginIp - The IP address of the computer through which this user last signed in.
• lastLoginClient - The Client ID of the application through which this user accessed the Covata Platform.
• id - The ID of this Covata user account.
• lastLoginTime - The date/time when this user last signed in by entering their Covata user credentials.
• accountType - A member containing the internationalization (I18N) property key/code ² for the account type, including the account type's value (i.e. hard-coded in the Covata Platform), as sub-members:
  • i18n - A member containing the I18N code ² for the account type as sub-members:
    • code - The I18N code for the account type's value, beginning with server.useraccounttype. This I18N code could include the substring local, ldap or external.
    • arguments - An array containing any arguments/variables that constitute the value of the I18N code above. Since none of the account types' values contain any variables, this array is always empty.
  • value - The value of accountType as it is hard-coded in the Covata Platform. Your client application can exploit this value (instead of i18n above) if I18N is not required.
  ² Your client application can exploit the Covata Platform's I18N features, by initially downloading the relevant language bundles (from the the Covata Platform), then using the i18n code (and if applicable, arguments) values above to extract the property values derived from these language bundles for use in your client application. For more information about the Covata Platform's I18N features, see Managing internationalization in the Safe Share Administrator's Guide.
  Note: For more information about account types, see the description for Account Type in the Organization Administrator's Guide.
  Example (response):

  {
      "externalUserId": null,
      "email": "alex.originator@xy-company.com",
      "firstName": "Alex",
      "lastName": "Originator",
      "otherName": null,
      "mobileNumber": null,
      "mfaEnabled": false,
      "systemAdmin": false,
      "homeOrganisationId": "759955653086449664",
      "i18nPreferenceCode": "en_us",
      "notificationFrequency": "ITEM",
      "lastLoginIp": "127.0.0.1",
      "lastLoginClient": "exampleClientApplication",
      "id": "759956629344260096",
      "lastLoginTime": "2016-09-29T23:29:05.443Z",
      "accountType": {
          "i18n": {
              "code": "server.useraccounttype.local",
              "arguments": []
          },
          "value": "LOCAL"
      }
  }