Audit Trail

Quickstart

Get started with the WorkOS Audit Trail and send your first event

Example Integration

app.js

file_copy
import WorkOS from '@workos-inc/node';
const workos = new WorkOS('{secretKey}');

app.post('/login', async (req, res) => {
  const { user } = req;

  const event = {
    group: user.org.domain,
    action: 'user.login',
    action_type: 'C',
    actor_name: user.email,
    actor_id: user.id,
    target_name: user.email,
    target_id: user.name,
    location: req.ip,
    occurred_at: new Date(),
    metadata: {
      description: 'User logged in.',
      request_id: req.headers['request-id'],
    },
  };

  void workos.createEvent(event);

  res.redirect('/');
});

Demo App

To begin, information related to a user login will be sent to WorkOS. The code above will create an event object, and log it in your Developer Dashboard.

1. Get your API key

WorkOS authenticates your API requests using your team's API key. If you do not include your key when making an API request, or include an incorrect key, WorkOS returns a 401 error.

Your team's API key is available in the Developer Dashboard.

2. Install an SDK

We currently provide official libraries for JavaScript and Go.

JavaScript

Available via Yarn:

Terminal

file_copy
yarn add @workos-inc/node

And via npm:

Terminal

file_copy
npm i @workos-inc/node

For more details, refer to the Node SDK documentation.

You can also view the source on GitHub.

Go

Install via go:

Terminal

file_copy
go get -u github.com/workos-inc/workos-go

Then, import the package:

main.go

file_copy
import (
  "github.com/workos-inc/workos-go/audittrail"
)

For more details, refer to the Go SDK documentation.

You can also view the source on GitHub.

3. Make an API request

Now it's time to test that your integration is working correctly. Make an API request using your secret key to publish your first event.

cURL

Terminal

file_copy
curl --request POST \
    --url https://api.workos.com/events \
    --header "Authorization: Bearer {secretKey}" \
    -d group="example.com" \
    -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-07-14T16:05:19.473Z"

JavaScript

import WorkOS from '@workos-inc/node';

const workos = new WorkOS('{secretKey}');

const event = {
  group: 'example.com',
  location: '65.215.8.114',
  action: 'user.login_succeeded',
  action_type: 'r',
  actor_name: 'annie.easley@{foo-corp.com}.',
  actor_id: 'user_01DEQWZNQT8Y47HDPSJKQS1J3F',
  target_name: 'annie.easley@{foo-corp.com}',
  target_id: 'user_01DEQWZNQT8Y47HDPSJKQS1J3F',
  occurred_at: new Date(),
};

workos.auditTrail.createEvent(event);

Go

package main
  
  import "github.com/workos-inc/workos-go/pkg/audittrail"
  
  func main() {
    audittrail.SetAPIKey("{secretKey}")
  
    err := audittrail.Publish(context.Background(), audittrail.Event{
        Action:     "user.login_succeeded",
        ActionType: audittrail.Read,
        ActorName:  "ethyl@dedicated.ai",
        ActorID:    "user_01DGZ0F97X0SXJB6D8KB8R0F7B",
        Group:      "dedicated.ai",
        Location:   "27.10.230.99",
        OccurredAt: time.Now(),
        TargetName: "ethyl@dedicated.ai",
        TargetID:   "user_01DGZ0F97X0SXJB6D8KB8R0F7B",
    })
    if err != nil {
        // Handle error.
    }
  }

In response, WorkOS returns:

JSON

file_copy
{ "success": true }

Then, view your test event in the Developer Dashboard.

Congratulations! You've successfully sent your first event using the WorkOS Audit Trail!