audittrail

README

audittrail

A Go package to send audit trails events to WorkOS.

Install

go get -u github.com/workos-inc/workos-go/pkg/audittrail

How it works

package main

import "github.com/workos-inc/workos-go/pkg/audittrail"

func main() {
    audittrail.SetAPIKey("my_api_key")

    // Wherever you need to publish an audit trail event:
    err := audittrail.Publish(ctx.Background(), audittrail.EventOpts{
        Action:     "document.viewed",
        ActionType: audittrail.Create,
        ActorName:  "Jairo Kunde",
        ActorID:    "user_01DGZ0FAXN978HCET66Q98QMTQ",
        Group:      "abstract.com",
        Location:   "55.27.223.26",
        OccurredAt: time.Now(),
        TargetName: "central.class",
        TargetID:   "doc_01DGZ0FAXP4HA4X0BVFKS0ZH4Y",
    })
    if err != nil {
        // Handle error.
    }
}

Documentation

Overview

Package `audittrail` provides a client wrapping the WorkOS Audit Trail API.

Example:

func main() {
    audittrail.SetAPIKey("my_api_key")

    // Wherever you need to publish an audit trail event:
    err := audittrail.Publish(context.Background(), audittrail.EventOpts{
        Action:     "document.viewed",
        ActionType: audittrail.Create,
        ActorName:  "Jairo Kunde",
        ActorID:    "user_01DGZ0FAXN978HCET66Q98QMTQ",
        Group:      "abstract.com",
        Location:   "55.27.223.26",
        OccurredAt: time.Now(),
        TargetName: "central.class",
        TargetID:   "doc_01DGZ0FAXP4HA4X0BVFKS0ZH4Y",
    })
    if err != nil {
        // Handle error.
    }
}

Index

• Constants
• func Publish(ctx context.Context, e EventOpts) error
• func SetAPIKey(k string)
• type Client
  • func (c *Client) ListEvents(ctx context.Context, opts ListEventsOpts) (ListEventsResponse, error)
  • func (c *Client) Publish(ctx context.Context, e EventOpts) error
• type Event
• type EventAction
• type EventOpts
• type ListEventsOpts
• type ListEventsResponse
  • func ListEvents(ctx context.Context, opts ListEventsOpts) (ListEventsResponse, error)
• type Metadata

Constants

const ResponseLimit = 10

ResponseLimit is the default number of records to limit a response to.

Functions

func Publish

func Publish(ctx context.Context, e EventOpts) error

Publish publishes the given event.

func SetAPIKey

func SetAPIKey(k string)

SetAPIKey sets the WorkOS API key to use when using Publish.

Types

type Client

type Client struct {
	// The WorkOS api key. It can be found in
	// https://dashboard.workos.com/api-keys.
	APIKey string

	// The http.Client that is used to post audit trail events to WorkOS. Defaults
	// to http.Client.
	HTTPClient *http.Client

	// The endpoint used to request Workos. Defaults to
	// https://api.workos.com/events.
	Endpoint string

	// The function used to encode in JSON. Defaults to json.Marshal.
	JSONEncode func(v interface{}) ([]byte, error)
	// contains filtered or unexported fields
}

Client represents a client that performs audittrail requests to WorkOS API.

func (*Client) ListEvents

func (c *Client) ListEvents(ctx context.Context, opts ListEventsOpts) (ListEventsResponse, error)

ListEvents gets a list of Audit Trail events.

func (*Client) Publish

func (c *Client) Publish(ctx context.Context, e EventOpts) error

Publish publishes the given event.

type Event

type Event struct {
	// Event identifier.
	ID string `json:"id"`

	// A single domain containing related members.
	Group string `json:"group"`

	// Identifier for where the Event originated.
	Location string `json:"location"`

	// Latitude for where the Event originated.
	Latitude string `json:"latitude"`

	// Longitude for where the Event originated.
	Longitude string `json:"longitude"`

	// Corresponding CRUD category of the Event.
	Type string `json:"event_type"`

	// Display name of the entity performing the action.
	ActorName string `json:"actor_name"`

	// Unique identifier of the entity performing the action.
	ActorID string `json:"actor_id"`

	// Display name of the object or resource that is being acted upon.
	TargetName string `json:"target_name"`

	// Unique identifier of the object or resource being acted upon.
	TargetID string `json:"target_id"`

	// ISO-8601 datetime at which the Event happened.
	OccurredAt string `json:"occurred_at"`

	// Specific activity performed by the actor.
	Action EventAction `json:"action"`

	// Arbitrary key-value data containing information associated with the Event
	Metadata Metadata `json:"metadata"`
}

Event describes an Audit Trail Event record.

type EventAction

type EventAction struct {
	// Event Action identifier.
	ID string `json:"id"`

	// Event Action name.
	Name string `json:"name"`

	// Identifier for the environment the Event Action belongs to.
	EnvironmentID string `json:"environment_id"`
}

EventAction describes an Audit Trail Event Action record.

type EventOpts

type EventOpts struct {
	// Specific activity performed by the actor.
	Action string `json:"action"`

	// Corresponding CRUD category of the Event.
	ActionType string `json:"action_type"`

	// Display name of the entity performing the action.
	ActorName string `json:"actor_name"`

	// Unique identifier of the entity performing the action.
	ActorID string `json:"actor_id"`

	// A single domain containing related members.
	Group string `json:"group"`

	// If no key is provided or the key is empty, the key will not be attached
	// to the request.
	IdempotencyKey string `json:"-"`

	// An ip address that locates where the audit trail occurred.
	Location string `json:"location"`

	// The event metadata. It can't contain more than 50 keys. A key can't
	// exeed 40 characters.
	Metadata Metadata `json:"metadata,omitempty"`

	// The time when the audit trail occurred.
	//
	// Defaults to time.Now().
	OccurredAt time.Time `json:"occurred_at"`

	// Display name of the object or resource that is being acted upon.
	TargetName string `json:"target_name"`

	// Unique identifier of the object or resource being acted upon.
	TargetID string `json:"target_id"`
}

EventOpts represents arguments to create an Audit Trail event.

type ListEventsOpts

type ListEventsOpts struct {
	// List of Groups to filter for.
	Group []string `url:"group,brackets,omitempty"`

	// List of Actions to filter for.
	Action []string `url:"action,brackets,omitempty"`

	// List of Action Types to filter for.
	ActionType []string `url:"action_type,brackets,omitempty"`

	// List of Actor Names to filter for.
	ActorName []string `url:"actor_name,brackets,omitempty"`

	// List of Actor IDs to filter for.
	ActorID []string `url:"actor_id,brackets,omitempty"`

	// List of Target Names to filter for.
	TargetName []string `url:"target_name,brackets,omitempty"`

	// List of Target IDs to filter for.
	TargetID []string `url:"target_id,brackets,omitempty"`

	// ISO-8601 datetime of when an event occurred.
	OccurredAt string `url:"occurred_at,omitempty"`

	// ISO-8601 datetime of when an event occurred after.
	OccurredAtGt string `url:"occurred_at_gt,omitempty"`

	// ISO-8601 datetime of when an event occurred at or after.
	OccurredAtGte string `url:"occurred_at_gte,omitempty"`

	// ISO-8601 datetime of when an event occurred before.
	OccurredAtLt string `url:"occurred_at_lt,omitempty"`

	// ISO-8601 datetime of when an event occured at or before.
	OccurredAtLte string `url:"occurred_at_lte,omitempty"`

	// Keyword search.
	Search string `url:"search,omitempty"`

	// Maximum number of records to return.
	Limit int `url:"limit"`

	// Pagination cursor to receive records before a provided Event ID.
	Before string `url:"before,omitempty"`

	// Pagination cursor to receive records after a provided Event ID.
	After string `url:"after,omitempty"`
}

ListEventsOpts contains options to fetch Audit Trail events.

type ListEventsResponse

type ListEventsResponse struct {
	// List of Events.
	Data []Event `json:"data"`

	// Cursor pagination options.
	ListMetadata common.ListMetadata `json:"listMetadata"`
}

ListEventsResponse describes the response structure when requesting Audit Trail events.

func ListEvents

func ListEvents(ctx context.Context, opts ListEventsOpts) (ListEventsResponse, error)

ListEvents fetches Audit Trail events.

type Metadata

type Metadata map[string]interface{}

Metadata represents metadata to be attached to an audit trail event.

var (
	// DefaultClient is the client used by SetAPIKey and Publish functions.
	DefaultClient = &Client{
		Endpoint: "https://api.workos.com/events",
	}

	// GlobalMetadata are metadata that are injected in every audit trail events.
	GlobalMetadata Metadata
)