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.
Where applicable, common elements of audit log events have moved from the v1's variable info_dict into the following common schema:
This gives a consistent schema for referencing users & assets across all event types.
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"
}
}
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.
The actor is the entity that performed the action, and represented by one of the following:
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.
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:
If the action was performed by Dropbox then the device origin is undefined.
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).
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.
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:
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.
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.
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 |
| 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
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:
| Event v1 | Event v2 |
| login_fail, emm_login_error, sso_error | login_fail |
| login_success | login_success |
| logout | logout |
| team_assume_user_start | sign_in_as_session_start |
| team_assume_user_end | sign_in_as_session_end |
| reseller_support_session_start | reseller_support_session_start |
| reseller_support_session_end | reseller_support_session_end |
| Event v1 | Event v2 |
| reset_all_passwords | password_reset_all |
| reset_password | password_reset |
| password_change | password_change |
| Event v1 | Event v2 |
| tfa_disable, tfa_edit_authenticator, tfa_edit_sms, tfa_enable | tfa_change_status |
| add_tfa_backup_phone | tfa_add_backup_phone |
| edit_tfa_backup_phone | tfa_change_backup_phone |
| remove_tfa_backup_phone | tfa_remove_backup_phone |
| add_tfa_security_key | tfa_add_security_key |
| remove_tfa_security_key | tfa_remove_security_key |
| tfa_reset | tfa_reset |
| Event v1 | Event v2 |
| change_sso_url, remove_sso_url | sso_change_login_url |
| remove_sso_url | sso_remove_login_url |
| update_sso_cert | sso_add_cert, sso_change_cert, sso_remove_cert |
| change_saml_identity_mode | sso_change_saml_identity_mode |
| change_logout_url | sso_add_login_url, sso_change_logout_url |
| remove_logout_url | sso_remove_logout_url |
| Event v1 | Event v2 |
| force_tfa_disable, force_tfa_enable | tfa_change_policy |
| allow_sso, require_sso, disable_sso | sso_change_policy |
| google_login_enabled, google_login_disabled | google_sso_change_policy |
| permanent_delete_enabled, permanent_delete_disabled | permanent_delete_change_policy |
| version_history_extended, version_history_limited | extended_version_history_change_policy |
| admin_set_account_capture_mode | account_capture_change_policy |
| twoaccount_desktop_enabled, twoaccount_desktop_disabled | twoaccount_change_policy |
| nts_enabled, nts_disabled | network_control_change_policy |
| smart_sync_default_changed_to_local, smart_sync_default_changed_to_on_demand | smart_sync_change_policy |
| allow_emm, require_emm, disable_emm | emm_change_policy |
| emm_user_excluded | emm_add_exception |
| emm_user_unexcluded | emm_remove_exception |
| device_management_desktops_limit_changed | device_approvals_change_desktop_policy |
| device_management_mobiles_limit_changed | device_approvals_change_mobile_policy |
| device_management_user_can_not_unapprove, device_management_user_can_unapprove | device_approvals_change_unlink_action |
| device_management_rollout_changed | device_approvals_change_overage_action |
| request_membership_disabled, request_membership_require_approval, request_membership_auto_accept | member_requests_change_policy |
| suggest_members_policy_disabled, suggest_members_policy_enabled | member_suggestions_change_policy |
| groups_all_users_can_create, groups_only_admins_can_create | group_user_management_change_policy |
| file_requests_enabled, file_requests_disabled | file_requests_change_policy |
| commenting_enabled, commenting_disabled | file_comments_change_policy |
| sf_external_invite_allow, sf_external_invite_forbid | sharing_change_member_policy |
| sf_external_accept_allow, sf_external_accept_forbid | sharing_change_folder_join_policy |
| shmodel_external_view_allow, shmodel_external_view_default_private, shmodel_external_view_forbid | sharing_change_link_policy |
| paper_disabled, paper_enabled | paper_change_policy |
| paper_deployment_policy_full, paper_deployment_policy_partial | paper_change_deployment_policy |
| web_session_management_idle_timeout | web_sessions_change_idle_length_policy |
| web_session_management_session_expiration | web_sessions_change_fixed_length_policy |
| office_addin_disabled, office_addin_enabled | microsoft_office_addin_change_policy |
| placement_restriction_changed | data_placement_restriction_change_policy |
| placement_restriction_fulfilled | data_placement_restriction_satisfy_policy |
| member_space_limits_exclusion_list_users_addition | member_space_limits_add_exception |
| member_space_limits_exclusion_list_users_removal | member_space_limits_remove_exception |
| member_space_limits_level_change | member_space_limits_change_policy |
| Event v1 | Event v2 |
| team_logo_added | team_profile_add_logo |
| team_logo_changed | team_profile_change_logo |
| team_logo_removed | team_profile_remove_logo |
| team_name_change | team_profile_change_name |
| Event v1 | Event v2 |
| csv_download | team_activity_create_report |
| smart_sync_no_admin_report_created | smart_sync_create_admin_privilege_report |
| emm_usage_report_created | emm_create_usage_report |
| emm_exclusion_users_report_created | emm_create_exceptions_report |
| Event v1 | Event v2 |
| admin_failed_domain_verification | domain_verification_add_domain_fail |
| admin_verified_a_domain | domain_verification_add_domain_success |
| admin_removed_a_domain | domain_verification_remove_domain |
| captured_user_left_domain | account_capture_relinquish_account |
| captured_user_migrated | account_capture_migrate_account |
| Event v1 | Event v2 |
| emm_token_refreshed | emm_refresh_auth_token |
| device_management_user_approval_blocked | device_link_fail |
| device_link | device_link_success |
| device_unlink | device_unlink |
| delete_on_unlink_fail | device_delete_on_unlink_fail |
| delete_on_unlink_success | device_delete_on_unlink_success |
| desktop_ip_changed | device_change_ip_desktop |
| mobile_ip_changed | device_change_ip_mobile |
| web_ip_changed | device_change_ip_web |
| Event v1 | Event v2 |
| app_allow | app_link_user |
| app_remove | app_unlink_user |
| team_app_allow | app_link_team |
| team_app_remove | app_unlink_team |
| Event v1 | Event v2 |
| member_invite, member_join, member_suspend, member_unsuspend, member_recover, member_leave | member_change_status |
| change_team_member_email | member_change_email |
| change_team_member_name | member_add_name, member_change_name |
| make_admin, change_admin_role, remove_admin | member_change_admin_role |
| permanently_delete_account_contents | member_permanently_delete_account_contents |
| transfer_account_contents | member_transfer_account_contents |
| suggest_team_members | member_suggest |
| change_membership_type | member_change_membership_type |
| member_space_user_usage_state_change | member_space_limits_change_status |
| Event v1 | Event v2 |
| group_created | group_create |
| group_deleted | group_delete |
| group_renamed | group_rename |
| group_changed_to_admin_managed, group_changed_to_member_managed | group_change_management_type |
| group_members_added | group_add_member |
| group_members_removed | group_remove_member |
| group_membertype_changed | group_change_member_role |
| group_external_id_changed | group_add_external_id, group_change_external_id, group_remove_external_id |
| Event v1 | Event v2 |
| team_folder_archive, team_folder_unarchive | team_folder_change_status |
| team_folder_create | team_folder_create |
| team_folder_permanently_delete | team_folder_permanently_delete |
| team_folder_rename | team_folder_rename |
| team_folder_downgraded | team_folder_downgrade |
| Event v1 | Event v2 |
| add_files, create_folder | file_add |
| rename_files_or_folders | file_rename |
| edit_files | file_edit |
| copy_files | file_copy |
| copy_reference_get | file_get_copy_reference |
| copy_reference_save | file_save_copy_reference |
| move_files | file_move |
| download_files | file_download |
| file_permanently_deleted | file_permanently_delete |
| preview_files | file_preview |
| restore_files | file_restore |
| revert_files_to_previous_version | file_revert |
| delete_files | file_delete |
| rollback_changes_in_files | file_rollback_changes |
| Event v1 | Event v2 |
| file_request_created | file_request_create |
| file_request_received_files | file_request_receive_file |
| close_file_request | file_request_close |
| change_file_request | file_request_change_title |
| change_file_request_folder | file_request_change_folder |
| add_users_to_file_request | file_request_send |
| add_file_request_deadline | file_request_add_deadline |
| remove_file_request_deadline | file_request_remove_deadline |
| Event v1 | Event v2 |
| add_comment | file_add_comment |
| delete_comment | file_delete_comment |
| resolve_comment | file_resolve_comment |
| unresolve_comment | file_unresolve_comment |
| subscribe_to_comment_notifications, unsubscribe_from_comment_notifications | file_change_comment_subscription |
| Event v1 | Event v2 |
| sf_create | shared_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_group | shared_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_access | shared_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_removed | shared_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_link | shared_content_claim_invitation |
| sf_request_access, shared_file_nonteam_request_access, shared_file_team_request_access | shared_content_request_access |
| sf_nonteam_invite, shared_file_nonteam_invite_member, sf_fb_invite, sf_team_invite, sf_invite_group | shared_content_add_invitees |
| sf_nonteam_uninvite, sf_fb_uninvite, sf_team_uninvite | shared_content_remove_invitees |
| sf_nonteam_invite_change_role, sf_fb_invite_change_role, sf_team_invite_change_role | shared_content_change_invitee_role |
| sf_nonteam_mount, sf_team_mount | shared_folder_mount |
| sf_nonteam_unmount, sf_team_unmount | shared_folder_unmount |
| sf_nonteam_transfer, sf_team_transfer | shared_folder_transfer_ownership |
| sf_nonteam_leave, sf_team_leave, sf_nonteam_decline, sf_team_decline | shared_content_relinquish_membership |
| sf_unshare, shared_file_unshare | shared_content_unshare |
| sf_downloads_off, sf_downloads_on, shared_file_downloads_off, shared_file_downloads_on | shared_content_change_downloads_policy |
| sf_viewer_info_off, sf_viewer_info_on, shared_file_viewer_info_off, shared_file_viewer_info_on | shared_content_change_viewer_info_policy |
| shared_content_nonteam_copy, shared_content_team_copy | shared_content_copy |
| shared_content_nonteam_download, shared_content_team_download | shared_content_download |
| shared_content_nonteam_view, shared_content_team_view | shared_content_view |
| sf_allow_invite_anyone, sf_allow_invite_team | shared_folder_change_members_policy |
| sf_allow_inviter_owner, sf_allow_inviter_team, sf_team_uninvite | shared_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_links | shared_folder_change_link_policy |
| shmodel_app_create, shmodel_create, shmodel_nonteam_create | shared_link_create |
| shmodel_disable | shared_link_disable |
| shmodel_group_share | shared_link_share |
| shmodel_nonteam_share, shmodel_team_share, shmodel_fb_share | shared_link_share |
| shmodel_nonteam_copy, shmodel_team_copy | shared_link_copy |
| shmodel_nonteam_download, shmodel_team_download | shared_link_download |
| shmodel_nonteam_view, shmodel_team_view | shared_link_view |
| shmodel_remove_expiration | shared_link_remove_expiry |
| shmodel_set_expiration | shared_link_add_expiry, shared_link_change_expiry |
| shmodel_visibility_password, shmodel_visibility_public, shmodel_visibility_team | shared_link_change_visibility |
| Event v1 | Event v2 |
| paper_permission_comment, paper_permission_edit, paper_permission_view | paper_doc_change_member_role |
| paper_doc_access_changed | paper_doc_change_sharing_policy |
| paper_doc_added_to_folder | paper_content_add_to_folder |
| paper_doc_archived, paper_doc_deleted | paper_content_archive |
| paper_doc_created | paper_content_create |
| paper_doc_delete_comment | paper_doc_delete_comment |
| paper_doc_docx_export, paper_doc_html_export, paper_doc_md_export | paper_doc_download |
| paper_doc_edit_comment | paper_doc_edit_comment |
| paper_doc_edited | paper_doc_edit |
| paper_doc_permanently_deleted | paper_content_permanently_delete |
| paper_doc_post_comment | paper_doc_add_comment |
| paper_doc_removed_from_folder | paper_content_remove_from_folder |
| paper_doc_renamed | paper_content_rename |
| paper_doc_resolve_comment | paper_doc_resolve_comment |
| paper_doc_restored | paper_content_restore |
| paper_doc_revision_restored | paper_doc_revert |
| paper_doc_unresolve_comment | paper_doc_unresolve_comment |
| paper_doc_nonteam_add_member, paper_doc_team_add_member, paper_doc_nonteam_invite, paper_doc_team_invite | paper_content_add_member |
| paper_doc_nonteam_mention, paper_doc_team_mention | paper_doc_mention |
| paper_doc_nonteam_request, paper_doc_team_request | paper_doc_request_access |
| paper_doc_nonteam_unshare, paper_doc_team_unshare | paper_content_remove_member |
| paper_doc_nonteam_view, paper_doc_team_view | paper_doc_view |