API Documentation
Toggle TOC panel
<access-service>/api/v1/users/{userId}/history

URL structure

1 https://access-service.xy-company.com/api/v1/users/{userId}/history

where {userId} is the ID of a Cocoon Data user account.

Supported methods and overview

  • GET - retrieves history information about account-related activities which have been performed on a Cocoon Data user account (specified by userId).

Detailed description

This API endpoint retrieves history information about account-related activities which have been performed on a Cocoon Data user account (specified by userId). Activities are retrieved in reverse chronological order.

The user's ID can be obtained by calling the GET method on either the <access-service>/api/v1/users/me or <access-service>/api/v1/organisations/{orgGroupId}/users endpoints, which retrieves a list of information associated with either the user whose access token is submitted in the request, or all users in the organisation specified by orgGroupId, respectively.

The extent of history information retrieved in a response depends on the role of the Cocoon Data user (whose access token is submitted in the request to this endpoint) and the user's organisation membership.

If this user is an Organisation administrator in the same organisation as that of the user represented by {userId} in the request's URL, then more information about the Organisation administrator who performed actions on the user account (represented by {userId}) can be returned in the response.

Supported roles and conditions

This API endpoint supports requests utilizing Cocoon Data user accounts with the following roles (as described in the SafeShare Administrator's and Organisation Administrator's Guides):

The Cocoon Data Platform's resources available to a Cocoon Data user meeting the criteria 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 optional parameters can also be sent in the URL of the GET request:

  • organisationId - The ID of the organisation from which to obtain more information about Organisation administrator activities on the user's account (specified by {userId} in the request's URL).
    Note: This parameter is only utilized by the Cocoon Data Platform when the Organisation administrator (whose access token is submitted in the request to this endpoint) is a member of the organisation represented by this organisationId parameter.
  • cursor - The ID for an activity entry (typically the chronologically previous one), retrieved in the response (below) from a request to this endpoint. This ID value relates to the activity entry that continues on from this response's last activity entry, which in turn was based on the combination of the values for cursor and pageSize (below) submitted in this response's request. The combination of these two parameters provides a mechanism for paginating activity entry results. If this cursor parameter is omitted, then its value is 0 by default, which is the most recent activity entry recorded on the item.
  • pageSize - A value from 1 to 100 indicating the number of activity entries to be returned in the response. If this parameter is omitted, then its value is 10 by default.
    Example (request):
    1 https://access-service.xy-company.com/api/v1/users/783190841862012928/history?pageSize=20

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:

  • nextCursor - The ID for the activity entry following the last element of the activities array (below) retrieved in the response. This is the chronologically previous activity entry (after the last one retrieved in this response).
  • previousCursor - The ID for the activity entry preceding the first element of the activities array (below) retrieved in the response. This is the chronologically next activity entry (before the first one retrieved in this response).
    Note: If the first activity entry is the most recent activity entry recorded on the item, then this value is 0.
  • activities - An array of individual activity entries on the Cocoon Data user account (represented by {userId} in the request's URL), listed in reverse chronological order. Each element of this array contains information about one of these activity entries and is represented as an object, containing the following members:
    • actor - A member containing information about the Cocoon Data user account that performed the action (below). This member contains the following sub-members:
      • type - Should be USER, indicating that this member contains information about a Cocoon Data user account.
      • id - The ID of the Cocoon Data user's account. If the actor is an Organisation administrator and the Cocoon Data user whose access token is submitted in the request to this endpoint (i.e. the 'requestor') is not an Organisation administrator of the organisation specified by organisationId in the request to this API endpoint, then this value will be -1.
      • email - The email address of this Cocoon Data user. If the actor is an Organisation administrator and the requestor is not an Organisation administrator of the organisation specified by organisationId in this endpoint's request, then this value will be an empty string.
      • firstName - The first name set by this Cocoon Data user. This is the first name that appears on the Users page of SafeShare Organisation Administration and the My Account feature of Cocoon Data SafeShare for Web. If the actor is an Organisation administrator and the requestor is not an Organisation administrator of the organisation specified by organisationId in this endpoint's request, then this value will be 'An'.
      • lastName - The last name set by this Cocoon Data user. Like the first name (above), this appears on the User page of Organisation Administration and the My Account feature of SafeShare for Web. If the actor is an Organisation administrator and the requestor is not an Organisation administrator of the organisation specified by organisationId in this endpoint's request, then this value will be 'Administrator'.
    • action - A string/enumeration (enum) value representing the individual action performed on the Cocoon Data user account (represented by {userId} in the request's URL).
      • User account modification through the My Account feature of SafeShare for Web (i.e. when the user themselves modifies their own account) - CHANGE_PROFILE, EXPIRE_ACCOUNT (a user's active sessions are terminated), CHANGE_PASSWORD, RESET_PASSWORD, ENABLE_MFA (two-factor authentication) and DISABLE_MFA.
      • Addition, modification or removal of a user account through the User page of SafeShare Organisation Administration (i.e. when an Organisation administrator adds, modifies or removes the account of a user who is a member of their organisation) - CREATE_ACCOUNT, CHANGE_ACCOUNT (e.g. a user account's plan is modified), UPGRADE_ACCOUNT (a user account's role is upgraded), TRANSFER_SUCCEEDED (a user's items were successfully transferred to another user within the same organisation), TRANSFER_FAILED and REMOVE_FROM_ORG.
      • UNKNOWN - Anything else that is not covered by an existing action (above).
    • severity - .
    • target - A member containing information about the Cocoon Data user account (i.e. {userId} in the request's URL) to which the action (above) was directed. This member contains the following sub-members:
      • type - Should be USER, indicating that this member contains information about a Cocoon Data user account.
      • id - The ID of the Cocoon Data user's account.
      • email - The email address of this Cocoon Data user.
      • firstName - The first name set by this Cocoon Data user. This is the first name that appears on the Users page of SafeShare Organisation Administration and the My Account feature of Cocoon Data SafeShare for Web.
      • lastName - The last name set by this Cocoon Data user. Like the first name (above), this appears on the User page of Organisation Administration and the My Account feature of SafeShare for Web.
    • timestamp - .
    Example (response):
    {
    "nextCursor": "0",
    "previousCursor": "0",
    "activities": [{
    "actor": {
    "type": "USER",
    "id": 783190841862012928,
    "email": "chris.collaborator@xy-company.com",
    "firstName": "Chris",
    "lastName": "Collaborator"
    },
    "action": "CHANGE_PASSWORD",
    "severity": "INFO",
    "target": {
    "type": "USER",
    "id": 783190841862012928,
    "email": "chris.collaborator@xy-company.com",
    "firstName": "Chris",
    "lastName": "Collaborator"
    },
    "timestamp": "2016-12-01T04:42:57.630Z"
    }, {
    "actor": {
    "type": "USER",
    "id": 783190841862012928,
    "email": "chris.collaborator@xy-company.com",
    "firstName": "Chris",
    "lastName": "Collaborator"
    },
    "action": "CHANGE_PROFILE",
    "severity": "INFO",
    "target": {
    "type": "USER",
    "id": 783190841862012928,
    "email": "chris.collaborator@xy-company.com",
    "firstName": "Chris",
    "lastName": "Collaborator"
    },
    "timestamp": "2016-12-01T04:42:35.312Z"
    }, {
    "actor": {
    "type": "USER",
    "id": -1,
    "email": "",
    "firstName": "An",
    "lastName": "Administrator"
    },
    "action": "CREATE_ACCOUNT",
    "severity": "INFO",
    "target": {
    "type": "USER",
    "id": 783190841862012928,
    "email": "chris.collaborator@xy-company.com",
    "firstName": "Chris",
    "lastName": "Collaborator"
    },
    "timestamp": "2016-12-01T04:40:47.762Z"
    }]
    }