Audit logs event reference

Audit log event schema

Hex audit logs are emitted in JSON format. Some notable fields in the schema are:

• action: type of action taken
• actor: identifies the user or client (e.g. API) making the request
• context: the location (IP address) and user agent of the actor
• targets: Hex resources that are affected or created by this action

The following is an example event object:

{
  "actor": {
    "id": "b44446e6-8264-4af5-a856-fdc2fa8fe132",
    "type": "USER",
    "metadata": {
      "email": "[email protected]",
      "workspace": "Hex",
      "workspaceId": "57c59cf9-c943-4386-afb5-75df1af3b2f7"
    }
  },
  "action": "RUN_CELL",
  "context": {
    "location": "1.1.1.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.0.0 Safari/537.36"
  },
  "targets": [
    {
      "id": "f426633a-0993-4bbc-be6a-740e28da2596",
      "type": "project",
      "metadata": {
        "representation": "{\"id\":\"f426633a-0993-4bbc-be6a-740e28da2596\",\"createdDate\":\"2024-04-08T20:15:06.337Z\",\"updatedDate\":\"2024-04-12T15:38:25.265Z\",\"archivedDate\":null,\"creatorId\":\"b44446e6-8264-4af5-a856-fdc2fa8fe132\",\"canEditorsShare\":true,\"projectLanguage\":\"PYTHON\",\"hexType\":\"PROJECT\",\"organizationRole\":null,\"publicRole\":null}"
      }
    },
    {
      "id": "60d9ac4d-7eb2-4638-9423-61bdf8a331ef",
      "type": "project_version",
      "metadata": {
        "representation": "{\"id\":\"60d9ac4d-7eb2-4638-9423-61bdf8a331ef\",\"createdDate\":\"2024-04-08T20:15:06.337Z\",\"updatedDate\":\"2024-04-12T15:38:25.127Z\",\"title\":\"Sample Project\",\"description\":\"\",\"hexId\":\"f426633a-0993-4bbc-be6a-740e28da2596\",\"creatorId\":\"b44446e6-8264-4af5-a856-fdc2fa8fe132\",\"timezone\":null,\"version\":\"draft\",\"published\":false,\"import\":false,\"kernelSize\":\"medium\",\"autoRerun\":true,\"cacheAppState\":true}"
      }
    },
    {
      "id": "340ba95d-465a-44d2-8b04-8a83c6c5b1e5",
      "type": "cell",
      "metadata": {
        "representation": "{\"id\":\"2e56c683-8151-4071-918f-0050ce854637\",\"createdDate\":\"2024-04-08T20:15:17.810Z\",\"updatedDate\":\"2024-04-08T20:15:17.810Z\",\"cellType\":\"SQL\"}"
      }
    }
  ],
  "version": 1,
  "metadata": {
    "result": "SUCCESS",
    "requestArgs": "{\"hexId\":\"f426633a-0993-4bbc-be6a-740e28da2596\",\"hexVersionId\":\"60d9ac4d-7eb2-4638-9423-61bdf8a331ef\",\"cellId\":\"2e56c683-8151-4071-918f-0050ce854637\"}",
    "failureReason": ""
  },
  "occurred_at": "2024-04-12T15:38:27.073Z"
}

Audit log target resource types

The following resource types appear as target resources in audit log events:

Resource type	Notes
Cell	A cell in a Hex project
Collection	A collection of Hex projects and components
Data connection	A connection to an external data warehouse
Domain	A domain allowed to be associated with your Hex workspace
External file integration	An integration with a cloud storage provider like AWS S3 or Google Drive
File	A file uploaded to a Hex project
Group	A group of Hex users that can be granted access to resources
Magic Api Key	An API key for authenticating magic requests
Project	A Hex project, component, or explore object
Project grant	A role (viewer, editor, etc.) given to a user or group for access to a Hex project
Project version	A specific version of a Hex project
Project view	An object that represents an instance of a user viewing a project
Scheduled run	A cron-like schedule on which a project is run periodically
Scheduled run notification	A notification configured on a scheduled run, to send emails and/or Slack messages when a scheduled run completes or fails
Semantic project	A semantic project containing shared definitions for data models
Secret	A secret value containing sensitive information that can be referenced in Hex projects
Template	A Hex-provided project template
User	A Hex user (could be email user, API user, etc.)
Workspace	A representation of your Hex workspace

Some event types include target resources with a type of principal. This indicates that this object can be one of multiple types. For instance, the UPDATE_PROJECT_ACCESS event type includes a principal resource which is either a Group or a User.

Audit log event types

Event type	Description	Target resource types
CREATE_PROJECT		Project
CREATE_PROJECT_FROM_TEMPLATE	Create a project from a template	Project Template
DUPLICATE_PROJECT		Project
COPY_PROJECT_FROM_EXTERNAL_WORKSPACE	Create a project by copying one from a different workspace	Project
IMPORT_PROJECT	Import a project from a project yaml file	Project
CREATE_EXPLORE_FROM_PROJECT_CELL	Create an "explore from app" from a project cell	Project
CREATE_EXPLORE	Create an Explore	Project Cell
CONVERT_EXPLORE_TO_PROJECT	Create a project from data created while exploring from an app	Project
VIEW_PROJECT		Project Project version Project view
RUN_PROJECT	Run a project top to bottom	Project Project version
RUN_CELL	Run a single cell within a project	Project Project version Cell
UPLOAD_FILE_TO_PROJECT		Project File
DOWNLOAD_FILE_FROM_PROJECT		Project File
PUBLISH_PROJECT		Project
DELETE_PROJECT	Move project to trash	Project
PERMANENTLY_DELETE_PROJECT		Project
REQUEST_PROJECT_ROLE	A user request for an access role to a project	Project User
GRANT_USERS_PROJECT_ACCESS	Grant a set of users an access role to a project	Project User Project grant
GRANT_GROUPS_PROJECT_ACCESS	Grant a set of groups an access role to a project	Project Group Project grant
GRANT_ADMIN_PROJECT_ACCESS	Same as GRANT_USERS_PROJECT_ACCESS, but only for admins	Project User Project grant
UPDATE_ALLOW_EMBEDDING	Enable signed embedding for the project	Project
UPDATE_PROJECT_ACCESS	Update the access role to a project for a set of users and/or groups	Project Principal Project grant Principal here refers to either a Group or a User
REMOVE_PROJECT_ACCESS	Remove a user or group's access to a project	Project Principal
SHARE_PROJECT_WITH_SUPPORT		Project
SHARE_PROJECT_WITH_ORG		Project
SHARE_PROJECT_WITH_PUBLIC		Project
UPDATE_PROJECT_PUBLIC_DUPLICATION_ALLOWED	Change whether or not a project can be duplicated by users in another workspace	Project
CREATE_SCHEDULED_RUN		Project Scheduled run
EDIT_SCHEDULED_RUN		Project Scheduled run
DELETE_SCHEDULED_RUN		Project Scheduled run
CREATE_COLLECTION		Collection
EDIT_COLLECTION		Collection
ADD_PROJECTS_TO_COLLECTION	Add a set of projects to a collection	Collection Project
UPDATE_COLLECTION_ROLE_IN_PROJECT	Update the access role that a collection has for a project	Collection Project
CREATE_WORKSPACE_DATA_CONNECTION	Create a data connection usable across the workspace	Data connection
CREATE_PROJECT_DATA_CONNECTION	Create a data connection within a project	Data connection Project
EDIT_DATA_CONNECTION		Data connection
REFRESH_DATA_CONNECTION_SCHEMA	Trigger a refresh of the data schema for a data connection	Data connection
UPDATE_DATA_CONNECTION_MAGIC_USAGE	Update whether or not a data connection should be used for Magic generation	Data connection
IMPORT_DATA_CONNECTION	Import a data connection in a project	Data connection Project
REMOVE_DATA_CONNECTION_IMPORT	Unimport a data connection from a project	Data connection Project
DELETE_DATA_CONNECTION		Data connection
SET_WORKSPACE_DEFAULT_DATA_CONNECTION	Set a data connection as the default for the workspace	Data connection
CREATE_SEMANTIC_PROJECT		Semantic project
PUBLISH_SEMANTIC_PROJECT	Publish changes to a semantic project from the modeling workbench or via Semantic Model Sync	Semantic project
DELETE_SEMANTIC_PROJECT		Semantic project
CREATE_USERS		User
CREATE_PASSWORD_USER	Create a user who is allowed to login using a password	User
INVITE_USERS	Invite users to join the workspace by email	Workspace
INVITE_USER_AS_ADMIN	Invite a user to join the workspace as an admin	Workspace
ACTIVATE_USER		User
DEACTIVATE_USER		User
EDIT_USER	Update user metadata (excluding their workspace role)	User
UPDATE_USER_ROLE	Update a user's workspace role	User
REQUEST_ORG_ROLE	A user's request for a specific role in the workspace	User
GRANT_USER_API_ACCESS	Allow a user to generate API tokens and use them in requessts	User
REVOKE_USER_API_ACCESS	Prevent user from creating API tokens and reject requests containing tokens attributed to this user	User
CREATE_GROUP		Group
UPDATE_GROUP	Update metadata about a group (not its users)	Group
UPDATE_GROUP_MEMBERS	Add or remove users from a group	User Group
DELETE_GROUP		Group
CREATE_EXTERNAL_FILE_INTEGRATION		External file integration
EDIT_EXTERNAL_FILE_INTEGRATION		External file integration
DELETE_EXTERNAL_FILE_INTEGRATION		External file integration
DOWNLOAD_FILE_FROM_EXTERNAL_FILE_INTEGRATION		External file integration
ADD_WORKSPACE_DOMAIN	Add an allowed domain to workspace	Domain
DELETE_WORKSPACE_DOMAIN		Domain
UPDATE_SSO_CONFIGURATION	Configure SSO auth for the workspace	Workspace
UPDATE_PUBLIC_SHARING_SETTING	Update whether or not projects in the workspace can be shared publicly	Workspace
UPDATE_API_TOKEN_EXPIRATION_POLICY	Configure expiration policy for API tokens	Workspace
UPDATE_ALLOW_NOTION_PREVIEW		Workspace
UPDATE_ALLOW_CSV_DOWNLOADS		Workspace
UPDATE_ALLOW_FILE_UPLOADS		Workspace
SET_DIRECTORY_SYNC_ADMIN_GROUP	Set a group of users from Directory Sync to be workspace admins	Workspace
SET_DIRECTORY_SYNC_AUTHOR_GROUP	Set a group of users from Directory Sync to be workspace editors	Workspace
SET_DATA_RETENTION_CELL_OUTPUTS	Set the data retention period for cell outputs	Workspace
SET_DATA_RETENTION_QUERY_CACHE	Set the data retention period for query cache entries	Workspace
CREATE_WORKSPACE_SECRET	Create a shared workspace secret	Secret
EDIT_WORKSPACE_SECRET	Modify properties of a shared workspace secret	Secret
DELETE_WORKSPACE_SECRET		Secret
IMPORT_WORKSPACE_SECRET	Import a shared workspace secret into a project	Secret
UNIMPORT_WORKSPACE_SECRET	Unimport a shared workspace secret from a project	Secret
CREATE_PROJECT_SECRET	Create a secret usable within a single project	Secret
EDIT_PROJECT_SECRET	Modify properties of a project-scoped secret	Secret
DELETE_PROJECT_SECRET		Secret
CREATE_SCHEDULED_RUN_NOTIFICATION	Create a new notification for a scheduled run	Scheduled Run Scheduled Run Notification Project
EDIT_SCHEDULED_RUN_NOTIFICATION	Edit an existing notification for a scheduled run	Scheduled Run Scheduled Run Notification Project
DELETE_SCHEDULED_RUN_NOTIFICATION	Delete an existing notification for a scheduled run	Scheduled Run Scheduled Run Notification
CREATE_MAGIC_API_KEY		Magic API Key
DELETE_MAGIC_API_KEY		Magic API Key
EXPORT_AS_PDF	Export a published app as PDF	Project Project version
DOWNLOAD_AS_CSV	Download outputs from a cell to CSV	Cell Project Project version
UPDATE_NOTEBOOK_CHAT_ALPHA_FEATURE_SETTING	Show whether the Notebook Agent's Alpha features are toggled on or off	User
CREATE_LOGIC_VIEW_AGENT_CHAT_MESSAGE	Show when a message gets sent to the Notebook agent	Agent Chat Message
MAGIC_EDIT_CELL	Notebook agent is used to edit the contents of an existing cell (e.g., modifying code in a SQL or Python cell)	Magic Event
MAGIC_DESCRIBE_PROJECT	Notebook agent is used to generate a project's description	Magic Event
MAGIC_NAME_PROJECT	Notebook agent names a project	Magic Event
MAGIC_RENAME_CELL	Notebook agent renames a cell	Magic Event
MAGIC_RENAME_CELL_OUTPUT	Notebook agent renames the output of a cell	Magic Event
CREATE_THREAD	A user creates a new Thread	Project
CREATE_PROJECT_FROM_THREAD	A user creates a project initiated from a Thread	Project
DUPLICATE_THREAD	A user duplicates a Thread that was shared with them	Project