Audit trails API reference

HCP Terraform retains 14 days of audit log information. The audit trails API exposes a stream of audit events, which describe changes to the application entities (workspaces, runs, etc.) that belong to an HCP Terraform organization. Unlike other APIs, the Audit Trails API does not use the JSON API specification.

List an organization's audit events

GET /organization/audit-trail

Query Parameters

These are standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --request GET \  "https://app.terraform.io/api/v2/organization/audit-trail?page[number]=1&since=2020-05-30T17:52:46.000Z"

Sample Response

{  "data": [    {      "id": "ae66e491-db59-457c-8445-9c908ee726ae",      "version": "0",      "type": "Resource",      "timestamp": "2020-06-30T17:52:46.000Z",      "auth": {        "accessor_id": "user-MaPuLxAXvtq2PWTH",        "description": "pveverka",        "type": "Client",        "impersonator_id": null,        "organization_id": "org-AGLwRmx1snv34Yts"      },      "request": {        "id": "4df584d4-7e2a-01e6-6cc0-4adbefa020e6"      },      "resource": {        "id": "at-sjt83qTw3GZatuPm",        "type": "authentication_token",        "action": "create",        "meta": null      }    }  ],  "pagination": {    "current_page": 1,    "prev_page": null,    "next_page": 2,    "total_pages": 8,    "total_count": 778  }}

Standard response fields

Every audit log event in the response array includes the following standard fields:

The following audit trail events only contain these standard fields:

The following sections list the audit log events containing both the standard response schema and a specific payload for each action.

Data retention policy events

You can define data retention policies to help reduce object storage consumption.

Destroy

An HCP Terraform organization emits this event when it destroys a data retention policy(data_retention_policy). Alongside the standard audit trail fields, this event response includes the following fields:

Project events

Projects let you organize your workspaces and scope access to workspace resources.

Add Team

An HCP Terraform organization emits this event when someone in your organization adds a team(add_team) to a project. Alongside the standard audit trail fields, this event response includes the following fields:

Update Team Permissions

An HCP Terraform organization emits this event when someone in your organization updates the permissions(update_team_permissions) of a team on a project. Alongside the standard audit trail fields, this event response includes the following fields:

Remove Team

An HCP Terraform organization emits this event when someone in your organization removes a team(remove_team) from a project. Alongside the standard audit trail fields, this event response includes the following fields:

Policy checks

Policy checks run Sentinel policies. Policy checks have a lifecycle that includes the following events:

• passed
• queued
• passed
• soft_failed
• hard_failed
• overridden
• canceled
• force_canceled
• errored

Every policy check event in the response array includes the following standard fields:

Passed, soft failed, hard failed, and errored

Alongside the standard audit trail fields and standard policy check fields, certain policy check events include a result (includes_result) and return the following fields:

Overridden, canceled, and force canceled

Alongside the standard audit trail fields and standard policy check fields, certain event responses include the following fields:

Policy evaluation

Policy evaluations run in the HCP Terraform agent in HCP Terraform's infrastructure. Policy evaluations have a lifecycle that includes the following events:

• queue
• run
• pass
• fail
• override
• error
• cancel
• force_cancel

Every policy evaluation event in the response array includes the following standard fields:

Policy checks and policy evaluations serve the same purpose, but have different workflows for enforcing policies. For more information, refer to Differences between policy checks and policy evaluations.

Registry module events

HCP Terraform's private registry lets you share Terraform providers and Terraform modules across your organization.

Destroy version

An HCP Terraform organization emits this event when someone in your organization destroys a specific version of a registry module(destroy_version). Alongside the standard audit trail fields, this event response includes the following fields:

Run task events

You can create HCP Terraform run tasks at an organization level to directly integrate third-party tools and services at certain stages in the HCP Terraform run lifecycle. You can use run tasks to validate Terraform configuration files, analyze execution plans before applying them, scan for security vulnerabilities, or perform other custom actions.

Create

An HCP Terraform organization emits this event when someone in your organization creates a task. Alongside the standard audit trail fields, this event response includes the following fields:

Destroy

An HCP Terraform organization emits this event when someone in your organization destroys a task. Alongside the standard audit trail fields, this event response includes the following fields:

Update

An HCP Terraform organization emits this event when someone in your organization updates a task. Alongside the standard audit trail fields, this event response includes the following fields:

Callback

An HCP Terraform organization emits this event when a run task result's (task_result) callback action occurs. Alongside the standard audit trail fields, this event response includes the following fields:

Create a workspace's run task

An HCP Terraform organization emits this event when someone in your organization associates a new run task with a workspace (workspace_task). Alongside the standard audit trail fields, this event response includes the following fields:

Update a workspace's run task

An HCP Terraform organization emits this event when someone in your organization updates a workspace's associated run task (workspace_task). Alongside the standard audit trail fields, this event response includes the following fields:

Destroy a workspace's run task

An HCP Terraform organization emits this event when someone in your organization destroys a workspace's associated run task (workspace_task). Alongside the standard audit trail fields, this event response includes the following fields:

Team events

Teams are groups of HCP Terraform users within an organization.

Add Member

An HCP Terraform organization emits this event when someone in your organization adds a member(add_member) to a team. Alongside the standard audit trail fields, this event response includes the following fields:

Remove Member

An HCP Terraform organization emits this event when someone in your organization removes a member(remove_member) from a team. Alongside the standard audit trail fields, this event response includes the following fields:

Workspace comment events

Workspace comments allow users to leave feedback or record decisions about a run.

Create

An HCP Terraform organization emits this event when someone in your organization creates a comment on a workspace(workspace_comment). Alongside the standard audit trail fields, this event response includes the following fields:

Workspace events

HCP Terraform manages infrastructure collections with workspaces.

Add Team

An HCP Terraform organization emits this event when someone in your organization adds a team(add_team) to a workspace. Alongside the standard audit trail fields, this event response includes the following fields:

Update Team Permissions

An HCP Terraform organization emits this event when someone in your organization updates the permissions(update_team_permissions) of a team on a workspace. Alongside the standard audit trail fields, this event response includes the following fields:

Remove Team

An HCP Terraform organization emits this event when someone in your organization removes a team(remove_team) from a workspace. Alongside the standard audit trail fields, this event response includes the following fields: