Type '/' to Search

»Audit Trails API

Terraform Cloud 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 a Terraform Cloud organization. Audit trails are a paid feature that is available as part of the Terraform Cloud for Business upgrade package. Refer to the Terraform Cloud pricing page for more details. Unlike other APIs, the Audit Trails API does not use the JSON API specification.

Note: The Audit Trails API is not available for Terraform Enterprise.

»List an organization's audit events

GET /organization/audit-trail

Note: This endpoint cannot be accessed with a user token or team token. You must access it with an organization token.

»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.

ParameterDescription
sinceOptional. Returns only audit trails created after this date (UTC and in ISO8601 Format - YYYY-MM-DDTHH:MM:SS.SSSZ)
page[number]Optional. If omitted, the endpoint will return the first page.
page[size]Optional. If omitted, the endpoint will return 1000 audit events per page.

»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"

$ 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
  }
}

{
  "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
  }
}

»Response Schema

Each JSON object in the response data array will include the following details, if available:

KeyDescription
idThe ID of this audit trail (UUID format)
versionThe audit trail schema version
typeThe type of audit trail (defaults to Resource)
timestampUTC ISO8601 DateTime (e.g. 2020-06-16T20:26:58.000Z)
auth.accessor_idThe ID of audited actor (e.g. user-V3R563qtJNcExAkN)
auth.descriptionUsername of audited actor
auth.typeAuthentication Type (one of Client, Impersonated or System)
auth.impersonator_idThe ID of impersonating actor (if available)
auth.organization_idThe ID of organization (e.g. org-QpXoEnULx3r2r1CA)
request.idThe ID for request (if available) (UUID format)
resource.idThe ID of resource (e.g. run-FwnENkvDnrpyFC7M)
resource.typeType of resource (e.g. run)
resource.actionAction audited (e.g. applied)
resource.metaKey-value metadata about this audited event