Get Events v2 Migration Guide

The following guide will help you migrate from the Dropbox Business API endpoint of team/log/get_events in v1 to team_log/get_events in v2.

The team_log/get_events endpoint has been re-written in order to drastically improve normalization, predictability and functionality for API consumers.

Overview

Where applicable, common elements of audit log events have moved from the v1's variable info_dict into the following common schema:

  • Timestamp: The Dropbox timestamp representing when the action was taken.
  • Event Category: Category that this type of action belongs to.
  • Event Type: The particular type of action taken.
  • Involve Non Team Member: Boolean that specifies if a non-team member was involved in the event.
  • Actor: The entity (user, application, or other) who actually performed the action.
  • Context: The user or team on whose behalf the actor performed the action.
  • Origin: The device origin from which the actor performed the action including information about device host, IP address, location, session, etc. If the action was performed programmatically via the API the device represents the API client.
  • Participants: Additional users & groups (other than the context) whom are affected by the action.
  • Assets: Content assets involved in the action, when applicable. Currently these include Dropbox files and folders as well as Dropbox Paper content.
  • Details: The variable event schema applicable to this event type.

This gives a consistent schema for referencing users & assets across all event types.

Example

The changes & benefits of the v2 structure are best illustrated by example:

File Add, v1

        {
            "event_type": "add_files",
            "member_id": "dbmid:AABCD_JXBjElUPaMLW7XewoH7F1euVwLQceo",
            "info_dict": {
                "path": "/folder/office.jpg",
                "is_dir": false,
                "file_id": "1111111111AAAAAAAAAAAA",
                "host_id": 1000000000
            },
            "ip_address": "123.123.123.123",
            "city": "San Francisco",
            "user_id": 535134427,
            "name": "John Smith",
            "country": "US",
            "region": "California",
            "event_type_description": "Added files",
            "event_category": "files",
            "time": "2017-08-14T06:49:20+00:00",
            "email": "john@acme.com"
        }

File Add, v2

        {
            "timestamp": "2017-08-14T06:49:20Z",
            "event_category": {
                ".tag": "file_operations"
            },
            "actor": {
                ".tag": "user",
                "user": {
                    ".tag": "team_member",
                    "account_id": "dbid:ABCDMCvPlupS23WsLcsxD1q0I-fTX7gxRw",
                    "display_name": "John Smith",
                    "email": "john@acme.com",
                    "team_member_id": "dbmid:ABCD_JXBjElUPaMLW7XewoH7F1euVwLQceo"
                }
            },
            "origin": {
                "geo_location": {
                    "city": "San Francisco",
                    "region": "California",
                    "country": "US",
                    "ip_address": "123.123.123.123"
                },
                "host": {
                    "host_id": 1000000000
                },
                "access_method": {
                    ".tag": "end_user",
                    "end_user": {
                        ".tag": "web"
                    }
                }
            },
            "involve_non_team_member": false,
            "context": {
                ".tag": "team_member",
                "account_id": "dbid:ABCDMCvPlupS23WsLcsxD1q0I-fTX7gxRw",
                "display_name": "John Smith",
                "email": "john@acme.com",
                "team_member_id": "dbmid:ABCD_JXBjElUPaMLW7XewoH7F1euVwLQceo"
            },
            "assets": [
                {
                    ".tag": "file",
                    "path": {
                        "contextual": "/folder/office.jpg",
                        "namespace_relative": {
                            "ns_id": "1122112231",
                            "relative_path":"office.jpg"
                        }
                    },
                    "file_id": "id:1111111111AAAAAAAAAAAA",
                }
            ],
            "event_type": {
                ".tag": "file_add",
                "description":"Added files and/or folders."
            },
            "details": {
                ".tag": "file_add_details"
            }
        }

v2 Schema Types

Common attributes of the v2 endpoint are described above, in the 'overview' section. Timestamp, event category, event type, and involve non team member are simple types. The complex types are described in more detail below.

Actor

The actor is the entity that performed the action, and represented by one of the following:

  • User: The action was manually performed by a Dropbox user.
  • Team Admin: The action was manually performed by a Dropbox user, who is a team administrator.
  • Application: The action was programmatically performed by a Dropbox API app, which may be a user-linked app or a team-linked app.
  • Reseller: The action was performed by the team's Dropbox Reseller supporting the team.
  • Dropbox: The action was manually or programmatically performed by Dropbox.

Context

The context is the user or team on whose behalf the actor performed the action. In many cases, the user in context is the same as the event actor. In general:

If the actor is ... then the action is performed in the context of ...
a user that user.
a team admin the team for which the actor is a team admin or a member of that team.
a user-linked app a user linked to the app.
a team-linked app a team linked to the app or a member of that team.
a reseller a team that was provisioned by that reseller or a member of that team.
Dropbox the current team or a member of the current team.

An event context can be an individual user or a team. Note that actors & context may represent users whom are not members of the team. For example, a user collaborating with your team in a share.

Origin

The device origin from which the action was performed. Device information includes IP address, geographical location and, if known, host information. Importantly, it also includes the method in which Dropbox was accessed from the device to perform the action.

The following access methods include:

  • End User Session: The action was performed manually with regular end user privileges (even if it was performed by a team admin) from the mobile app, the desktop client or the (non-admin) Web app.
  • Sign-in-as Session: The action was performed manually by a team admin, or a reseller acting as a team admin delegate, who has signed-in-as the user in event context from the Admin Console Web app.
  • Content Manager Session: The action was performed manually by a team admin, or a reseller acting as a team admin delegate, in the content manager component of the Admin Console Web app.
  • Admin Console Session: The action was performed manually by a team admin, or a reseller acting as a team admin delegate, in the Admin Console Web app outside of content manager.
  • API: The action was performed programmatically by an app via the API and is associated with an API request ID.

If the action was performed by Dropbox then the device origin is undefined.

Participants

Participants of an event are additional users and/or groups that are affected by the action, if any. Participants exclude both users who directly performed the action (actor) and those whom the action was performed on behalf of (context user).

Assets

Content assets involved in the action. Currently this includes files & folders as well as Paper docs & folders.

Files & folders assets may contain a namespace-relative path (namespace_id + relative_path), a contextual path, a file_id, and/or a display name.

For example:

    "assets": [
        {
          ".tag": "file",
          "path": {
              "contextual": "/folder/office.jpg",
              "namespace_relative": {
                  "ns_id": "1122112231"
                  "relative_path":"office.jpg"
              }
          },
          "display_name":""
          "file_id": "id:1111111111AAAAAAAAAAAA"
      }

While namespace_relative paths (ns_id + relative_path) and file_id's are unique, the contextual path is relative to the user in the context.

    "context": {
        ".tag": "team_member",
        "account_id": "dbid:ABCDMCvPlupS23WsLcsxD1q0I-fTX7gxRw",
        "display_name": "John Smith",
        "email": "john@acme.com",
        "team_member_id": "dbmid:ABCD_JXBjElUPaMLW7XewoH7F1euVwLQceo"
    }

Paper assets will return the corresponding doc or folder id.

Best Practices - Referring to Assets

The aforementioned identifiers that can be used to make calls to other parts of the Dropbox API for remediation actions. For example, if your app has team member file access, the identifiers from the file asset can be used for a variety of user endpoint calls, like files/download.

As a best practice, we recommend using an identifier instead of relative paths when possible. Use file_id, ns_id + namespace relative path, or ns_id+ file_id. Your application may prefer one of these identifiers over another, based on how it interacts with permissions & moves/renames.

Remember:

  • Namespaces have associated permissions
  • Files can be renamed & moved (across namespaces).
  • A file_id is a unique reference to file content, which does not change on rename & moves.
  • A contextual path is relative to the user; two users may have the same shared content mounted to different paths.
  • A display name, generally the filename, is shown for some shared assets. In some link sharing scenarios, your team may not be able to see the path information of shared content owned by other users / teams - and thus path information may be incomplete or omitted.

Dropbox supports two HTTP headers on user endpoints to simplify accessing team content with these identifiers on user endpoints. The Dropbox-Select-User header allows a team application to perform calls on behalf the specified user. The Dropbox-Select-Admin header simplifies many read operations, by allowing you to specify an administrator to access any team content (rather than specifying the particular owner within the team). See the namespace guide for more details.

Events v1 → v2

Historical Data & Optional Attributes

Be sure your application is able to handle attributes that are technically optional. Attributes marked as optional tend to be returned in normal scenarios, but they do not represent strong guarantees and may be omitted in some scenarios.

In particular, note that historical data is more likely have these optional attributes missing. As get_events v2 contains a richer schema then v1, events that transpired prior to usage of v2 may not have been recorded with these additional attributes.

Enrollment into the enhanced schema used by get_events v2 is done automatically on a per-team basis as the team links apps that can leverage the get_events endpoint. Thus your application can anticipate enriched events going forward, but may need to be particularly aware of optional attributes on events prior to the team linking the app.

Attribute Mapping

Event attributes from the v1 endpoint directly map to v2 as follows:

v1 v2
time timestamp
event_category event_category[.tag]
event_type event_type[.tag]
event_type_description event_type[.description]
user_id context.account_id*
member_id context.member_id
email context.team_member_id
name context.display_name
ip_address origin.geo_location.ip_address
city origin.geo_location.city
region origin.geo_location.region
country origin.geo_location.country
info_dict (Normalized into schema types)

*Note: formatting of this identifier has changed from numeric id to 'dbid:XX' identifier used elswhere in APIv2

Event Mapping

Many events have been renamed, and in some cases reclassified to another event category for clarity & consistency.

Refer to individual events team_log/get_events for complete up to date listing of v2 events types.

Key v1 events map to v2 event names, by v2 category, as follows:

logins

Event v1Event v2
login_fail, emm_login_error, sso_errorlogin_fail
login_successlogin_success
logoutlogout
team_assume_user_startsign_in_as_session_start
team_assume_user_endsign_in_as_session_end
reseller_support_session_startreseller_support_session_start
reseller_support_session_endreseller_support_session_end

passwords

Event v1Event v2
reset_all_passwordspassword_reset_all
reset_passwordpassword_reset
password_changepassword_change

tfa (two factor authentication)

Event v1Event v2
tfa_disable, tfa_edit_authenticator, tfa_edit_sms, tfa_enabletfa_change_status
add_tfa_backup_phonetfa_add_backup_phone
edit_tfa_backup_phonetfa_change_backup_phone
remove_tfa_backup_phonetfa_remove_backup_phone
add_tfa_security_keytfa_add_security_key
remove_tfa_security_keytfa_remove_security_key
tfa_resettfa_reset

sso

Event v1Event v2
change_sso_url, remove_sso_urlsso_change_login_url
remove_sso_urlsso_remove_login_url
update_sso_certsso_add_cert, sso_change_cert, sso_remove_cert
change_saml_identity_modesso_change_saml_identity_mode
change_logout_urlsso_add_login_url, sso_change_logout_url
remove_logout_urlsso_remove_logout_url

team_policies

Event v1Event v2
force_tfa_disable, force_tfa_enabletfa_change_policy
allow_sso, require_sso, disable_ssosso_change_policy
google_login_enabled, google_login_disabledgoogle_sso_change_policy
permanent_delete_enabled, permanent_delete_disabledpermanent_delete_change_policy
version_history_extended, version_history_limitedextended_version_history_change_policy
admin_set_account_capture_modeaccount_capture_change_policy
twoaccount_desktop_enabled, twoaccount_desktop_disabledtwoaccount_change_policy
nts_enabled, nts_disablednetwork_control_change_policy
smart_sync_default_changed_to_local, smart_sync_default_changed_to_on_demandsmart_sync_change_policy
allow_emm, require_emm, disable_emmemm_change_policy
emm_user_excludedemm_add_exception
emm_user_unexcludedemm_remove_exception
device_management_desktops_limit_changeddevice_approvals_change_desktop_policy
device_management_mobiles_limit_changeddevice_approvals_change_mobile_policy
device_management_user_can_not_unapprove, device_management_user_can_unapprovedevice_approvals_change_unlink_action
device_management_rollout_changeddevice_approvals_change_overage_action
request_membership_disabled, request_membership_require_approval, request_membership_auto_acceptmember_requests_change_policy
suggest_members_policy_disabled, suggest_members_policy_enabledmember_suggestions_change_policy
groups_all_users_can_create, groups_only_admins_can_creategroup_user_management_change_policy
file_requests_enabled, file_requests_disabledfile_requests_change_policy
commenting_enabled, commenting_disabledfile_comments_change_policy
sf_external_invite_allow, sf_external_invite_forbidsharing_change_member_policy
sf_external_accept_allow, sf_external_accept_forbidsharing_change_folder_join_policy
shmodel_external_view_allow, shmodel_external_view_default_private, shmodel_external_view_forbidsharing_change_link_policy
paper_disabled, paper_enabledpaper_change_policy
paper_deployment_policy_full, paper_deployment_policy_partialpaper_change_deployment_policy
web_session_management_idle_timeoutweb_sessions_change_idle_length_policy
web_session_management_session_expirationweb_sessions_change_fixed_length_policy
office_addin_disabled, office_addin_enabledmicrosoft_office_addin_change_policy
placement_restriction_changeddata_placement_restriction_change_policy
placement_restriction_fulfilleddata_placement_restriction_satisfy_policy
member_space_limits_exclusion_list_users_additionmember_space_limits_add_exception
member_space_limits_exclusion_list_users_removalmember_space_limits_remove_exception
member_space_limits_level_changemember_space_limits_change_policy

team_profile

Event v1Event v2
team_logo_addedteam_profile_add_logo
team_logo_changedteam_profile_change_logo
team_logo_removedteam_profile_remove_logo
team_name_changeteam_profile_change_name

reports

Event v1Event v2
csv_downloadteam_activity_create_report
smart_sync_no_admin_report_createdsmart_sync_create_admin_privilege_report
emm_usage_report_createdemm_create_usage_report
emm_exclusion_users_report_createdemm_create_exceptions_report

domains

Event v1Event v2
admin_failed_domain_verificationdomain_verification_add_domain_fail
admin_verified_a_domaindomain_verification_add_domain_success
admin_removed_a_domaindomain_verification_remove_domain
captured_user_left_domainaccount_capture_relinquish_account
captured_user_migratedaccount_capture_migrate_account

devices

Event v1Event v2
emm_token_refreshedemm_refresh_auth_token
device_management_user_approval_blockeddevice_link_fail
device_linkdevice_link_success
device_unlinkdevice_unlink
delete_on_unlink_faildevice_delete_on_unlink_fail
delete_on_unlink_successdevice_delete_on_unlink_success
desktop_ip_changeddevice_change_ip_desktop
mobile_ip_changeddevice_change_ip_mobile
web_ip_changeddevice_change_ip_web

apps

Event v1Event v2
app_allowapp_link_user
app_removeapp_unlink_user
team_app_allowapp_link_team
team_app_removeapp_unlink_team

members

Event v1Event v2
member_invite, member_join, member_suspend, member_unsuspend, member_recover, member_leavemember_change_status
change_team_member_emailmember_change_email
change_team_member_namemember_add_name, member_change_name
make_admin, change_admin_role, remove_adminmember_change_admin_role
permanently_delete_account_contentsmember_permanently_delete_account_contents
transfer_account_contentsmember_transfer_account_contents
suggest_team_membersmember_suggest
change_membership_typemember_change_membership_type
member_space_user_usage_state_changemember_space_limits_change_status

groups

Event v1Event v2
group_createdgroup_create
group_deletedgroup_delete
group_renamedgroup_rename
group_changed_to_admin_managed, group_changed_to_member_managedgroup_change_management_type
group_members_addedgroup_add_member
group_members_removedgroup_remove_member
group_membertype_changedgroup_change_member_role
group_external_id_changedgroup_add_external_id, group_change_external_id, group_remove_external_id

team_folders

Event v1Event v2
team_folder_archive, team_folder_unarchiveteam_folder_change_status
team_folder_createteam_folder_create
team_folder_permanently_deleteteam_folder_permanently_delete
team_folder_renameteam_folder_rename
team_folder_downgradedteam_folder_downgrade

file_operations

Event v1Event v2
add_files, create_folderfile_add
rename_files_or_foldersfile_rename
edit_filesfile_edit
copy_filesfile_copy
copy_reference_getfile_get_copy_reference
copy_reference_savefile_save_copy_reference
move_filesfile_move
download_filesfile_download
file_permanently_deletedfile_permanently_delete
preview_filesfile_preview
restore_filesfile_restore
revert_files_to_previous_versionfile_revert
delete_filesfile_delete
rollback_changes_in_filesfile_rollback_changes

file_requests

Event v1Event v2
file_request_createdfile_request_create
file_request_received_filesfile_request_receive_file
close_file_requestfile_request_close
change_file_requestfile_request_change_title
change_file_request_folderfile_request_change_folder
add_users_to_file_requestfile_request_send
add_file_request_deadlinefile_request_add_deadline
remove_file_request_deadlinefile_request_remove_deadline

comments

Event v1Event v2
add_commentfile_add_comment
delete_commentfile_delete_comment
resolve_commentfile_resolve_comment
unresolve_commentfile_unresolve_comment
subscribe_to_comment_notifications, unsubscribe_from_comment_notificationsfile_change_comment_subscription

sharing

Event v1Event v2
sf_createshared_folder_create
sf_nonteam_add_members, sf_team_add_members, group_sf_added, shared_file_nonteam_add_member, shared_file_team_add_member, shared_file_group_added, sf_add_groupshared_content_add_member
sf_nonteam_member_change_role, sf_team_member_change_role, group_sf_access_changed, shared_file_nonteam_change_role, shared_file_team_change_role, sf_nonteam_grant_access, sf_team_grant_accessshared_content_change_member_role
sf_nonteam_kick, sf_team_kick, group_sf_removed, shared_file_nonteam_remove_member, shared_file_team_remove_member, shared_file_group_removedshared_content_remove_member
sf_nonteam_claim_membership, sf_team_claim_membership, shared_file_nonteam_claim, shared_file_team_claim, sf_nonteam_join, sf_team_join, sf_nonteam_join_from_oob_link, sf_team_join_from_oob_linkshared_content_claim_invitation
sf_request_access, shared_file_nonteam_request_access, shared_file_team_request_accessshared_content_request_access
sf_nonteam_invite, shared_file_nonteam_invite_member, sf_fb_invite, sf_team_invite, sf_invite_groupshared_content_add_invitees
sf_nonteam_uninvite, sf_fb_uninvite, sf_team_uninviteshared_content_remove_invitees
sf_nonteam_invite_change_role, sf_fb_invite_change_role, sf_team_invite_change_roleshared_content_change_invitee_role
sf_nonteam_mount, sf_team_mountshared_folder_mount
sf_nonteam_unmount, sf_team_unmountshared_folder_unmount
sf_nonteam_transfer, sf_team_transfershared_folder_transfer_ownership
sf_nonteam_leave, sf_team_leave, sf_nonteam_decline, sf_team_declineshared_content_relinquish_membership
sf_unshare, shared_file_unshareshared_content_unshare
sf_downloads_off, sf_downloads_on, shared_file_downloads_off, shared_file_downloads_onshared_content_change_downloads_policy
sf_viewer_info_off, sf_viewer_info_on, shared_file_viewer_info_off, shared_file_viewer_info_onshared_content_change_viewer_info_policy
shared_content_nonteam_copy, shared_content_team_copyshared_content_copy
shared_content_nonteam_download, shared_content_team_downloadshared_content_download
shared_content_nonteam_view, shared_content_team_viewshared_content_view
sf_allow_invite_anyone, sf_allow_invite_teamshared_folder_change_members_policy
sf_allow_inviter_owner, sf_allow_inviter_team, sf_team_uninviteshared_folder_change_members_management_policy
sf_block_non_members_from_viewing_shared_links, sf_allow_anyone_to_view_shared_links, sf_allow_team_to_view_shared_links, sf_allow_non_members_to_view_shared_linksshared_folder_change_link_policy
shmodel_app_create, shmodel_create, shmodel_nonteam_createshared_link_create
shmodel_disableshared_link_disable
shmodel_group_shareshared_link_share
shmodel_nonteam_share, shmodel_team_share, shmodel_fb_shareshared_link_share
shmodel_nonteam_copy, shmodel_team_copyshared_link_copy
shmodel_nonteam_download, shmodel_team_downloadshared_link_download
shmodel_nonteam_view, shmodel_team_viewshared_link_view
shmodel_remove_expirationshared_link_remove_expiry
shmodel_set_expirationshared_link_add_expiry, shared_link_change_expiry
shmodel_visibility_password, shmodel_visibility_public, shmodel_visibility_teamshared_link_change_visibility

paper

Event v1Event v2
paper_permission_comment, paper_permission_edit, paper_permission_viewpaper_doc_change_member_role
paper_doc_access_changedpaper_doc_change_sharing_policy
paper_doc_added_to_folderpaper_content_add_to_folder
paper_doc_archived, paper_doc_deletedpaper_content_archive
paper_doc_createdpaper_content_create
paper_doc_delete_commentpaper_doc_delete_comment
paper_doc_docx_export, paper_doc_html_export, paper_doc_md_exportpaper_doc_download
paper_doc_edit_commentpaper_doc_edit_comment
paper_doc_editedpaper_doc_edit
paper_doc_permanently_deletedpaper_content_permanently_delete
paper_doc_post_commentpaper_doc_add_comment
paper_doc_removed_from_folderpaper_content_remove_from_folder
paper_doc_renamedpaper_content_rename
paper_doc_resolve_commentpaper_doc_resolve_comment
paper_doc_restoredpaper_content_restore
paper_doc_revision_restoredpaper_doc_revert
paper_doc_unresolve_commentpaper_doc_unresolve_comment
paper_doc_nonteam_add_member, paper_doc_team_add_member, paper_doc_nonteam_invite, paper_doc_team_invitepaper_content_add_member
paper_doc_nonteam_mention, paper_doc_team_mentionpaper_doc_mention
paper_doc_nonteam_request, paper_doc_team_requestpaper_doc_request_access
paper_doc_nonteam_unshare, paper_doc_team_unsharepaper_content_remove_member
paper_doc_nonteam_view, paper_doc_team_viewpaper_doc_view