Audit Trail

API Reference

Overview

The Audit Trail API is structured around REST semantics. It has predictable, resource-oriented, long-lived URIs. It also uses standard HTTP response status codes and verbs for accessing and modifying content.


Authentication

The Audit Trail API authenticates using your API key. Your team's API key is located in your Developer Dashboard.

API keys are passed using a Bearer token in the Authorization header.

Terminal

file_copy
Authorization: Bearer {secretKey}

Error Codes

WorkOS uses standard HTTP response codes to indicate the success or failure of your API requests.

Codes in the 2xx range indicate success.

Codes in the 4xx range indicate failure, normally due to error caused by incorrect or missing request information (e.g. providing an incorrect API key).

Codes in the 5xx range indicate an error with WorkOS's servers.


Events

The Event Object

Resource Endpoint:

POST /events

Events are objects containing information relevant to notable actions taken by users in your application. For example, when a user successfully logs in, a user.login_succeeded Event object is created that contains attributes such as the actor_name of the user who performed the action as well as the location and datetime the event occurred_at.

Example Event

JSON

file_copy
{
  "id": "evt_01DEQWZP0E4HD5WDEW1PRADR5E",
  "group": "workos.com",
  "location": "65.215.8.114",
  "action": "organization.added_user",
  "action_type": "r",
  "actor_name": "WorkOS",
  "actor_id": "org_01DEQRHKNW3HDTMRDJ2B9NM9YZ",
  "target_name": "admin@workos.com",
  "target_id": "user_01DEQWZNQT8Y9RBDPSJKQS1J3F",
  "metadata": {
    "description": "Organization added user.",
    "x_request_id": "DFEA9F0A-F201-4568-B50D-16277DCCD23A"
  },
  "occurred_at": "2020-04-09T04:17:33.729Z"
}

Attributes

  • id (string): Unique identifier for the event.
  • group (string): A single organization containing related members. This will normally be the customer of a vendor's application.
  • location (string): Identifier for where the event originated. This will be an IP address (IPv4 or IPv6), hostname, or device ID.
  • action (string): Specific activity performed by the actor.
  • action_type (string): Corresponding CRUD category of the event. Can be one of C, R, U, or D.
  • actor_name (string): Display name of the entity performing the action.
  • actor_id (string): Unique identifier of the entity performing the action.
  • target_name (string): Display name of the object or resource that is being acted upon.
  • target_id (string): Unique identifier of the object or resource being acted upon.
  • metadata (JSON object, optional): Arbitrary key-value data containing information associated with the event. Note: There is a limit of 50 keys. Key names can be up to 40 characters long, and values can be up to 500 characters long.
  • occurred_at (string): ISO-8601 datetime at which the event happened, with millisecond precision.

Event Types

This is a list of example events that you can send.

Notice these events follow the pattern: resource:event. It is our hope that by using this consistent pattern, event types will be easier to anticipate and code against.

  • organization.added_user: Describes an organization. Occurs whenever a new user is added to an organization.
  • organization.created: Describes an organization. Occurs whenever a new organization is created.
  • user.created: Describes a user. Occurs whenever a user is created.
  • user.login_failed: Describes a user. Occurs whenever a user login fails.
  • user.logged_out: Describes a user. Occurs whenever a user is logged out.
  • user.login_succeeded: Describes a user. Occurs whenever a user successfully logs in.
  • user.searched_api_logs: Describes a user. Occurs whenever a user searches top-level logs of API activity.
  • user.searched_audit_log_events: Describes a user. Occurs whenever a user searches events.
  • user.viewed_api_log_details: Describes a user. Occurs whenever a user views details of a specific API request event.
  • user.viewed_audit_log_event_details: Describes a user. Occurs whenever a user views details of a specific event.

Publish a Single Event

Publishes the details of a single event.

  • Endpoint: /events
  • HTTP Method:POST
  • Body: JSON eventobject
  • Response: 201 status code indicates WorkOS has successfully received the request

Example Request

Terminal

file_copy
curl --request POST \
    --url https://api.workos.com/events \
    --header "Authorization: Bearer {secretKey}" \
    -d group="Example Org" \
    -d location="65.215.8.114" \
    -d action="user.login_succeeded" \
    -d action_type="r" \
    -d actor_name="annie.easley@{foo-corp.com}" \
    -d actor_id="user_01DEQWZNQT8Y47HDPSJKQS1J3F" \
    -d target_name="annie.easley@{foo-corp.com}" \
    -d target_id="user_01DEQWZNQT8Y47HDPSJKQS1J3F" \
    -d occurred_at="2020-04-09T04:17:33.729Z"

Example Response

JSON

file_copy
{ "success": true }

Idempotency

The WorkOS API supports idempotent requests when publishing single events. This enables you to retry a request and know that the same operation isn't performed twice.

For example, consider: you're publishing an event, a network connection error interrupts your API request, and you don't receive a response. You can perform the request again using the same idempotency key, guaranteeing that you only publish one event.

Key Expiration

Idempotency keys expire after 24 hours, so we generate a new request if you reuse a key outside of that time frame.

To perform an idempotent request, provide an additional Idempotency-Key: <key> header to the request.

Example

Terminal

file_copy
curl --request POST \
    --url https://api.workos.com/events \
    --header "Authorization: Bearer {secretKey}" \
    -H "Idempotency-Key: 6d4c7400-d4bf-4623-a301-afe7b50569d3" \
    -d group="Fairchild Semiconductor" \
    -d location="65.215.8.114" \
    -d action="user.login_succeeded" \
    -d action_type="r" \
    -d actor_name="bob@fairchild.com" \
    -d actor_id="user_01DHJUNNQT8Y47HDPSJKQS1J3F" \
    -d target_name="bob@fairchild.com" \
    -d target_id="user_01DHJUNNQT8Y47HDPSJKQS1J3F" \
    -d occurred_at="2020-04-09T04:17:33.729Z"

Metadata

Each event object contains an optional metadata parameter. You can use this parameter to store arbitrary key-value data in the form of a JSON object. Metadata is useful for storing any additional, relevant or useful information about an object.

Keep in mind that there is a limit of 50 keys on metadata objects. Key names can be up to 40 characters long, and values can be up to 500 characters long.

Important!

Do not store any sensitive information (e.g. business or financial data, classified, or personally identifiable information) in any part of the metadata parameter!

Sample Use Cases

  • a human-readable description of the action taken
  • links to other pages within the application that contain more details
  • the web request ID or other application context (e.g. a filename or route)
  • the git hash of the current deployment

The Metadata field is not currently indexed for searching

Please let us know if you're interested in support for this feature!

Example

JSON

file_copy
{
  "id": "evt_01DEQX40VGBC60BJY5X18YE4JP",
  "group": "MIT",
  "location": "65.215.8.114",
  "action": "user.searched_audit_trail_events",
  "action_type": "r",
  "actor_name": "liskov@csail.mit.edu",
  "actor_id": "user_01DENJUHBG8Y9RB8U7SJKQS1J3F",
  "target_name": "http_request",
  "target_id": "DFEA9F0A-F201-4568-B50D-16277DCCD23A",
  "metadata": {
    "query": {
      "action": "user.created",
      "search": "system"
    },
    "event_ids": [
      "evt_01DEQWKYM5YQ5JYPXM5TQ8WY81",
      "evt_01DEQW6448C1KABJM9P0ZSPA5B"
    ],
    "description": "User searched audit trail events.",
    "x_request_id": "DFEA9F0A-F201-4568-B50D-16277DCCD23A"
  },
  "occurred_at": "2020-04-09T04:17:33.729Z"
}