Skip to main content

Using The Enterprise API

The Retraced Enterprise API enables users to consume audit log data programmatically and integrate it with an external monitoring or security system.

Creating and Managing Enterprise Tokens​

Enterprise Tokens can be created and managed via the Embedded Viewer

Note: If you're a vendor integrating Retraced as your audit log, you can also manage and distribute Enterprise Tokens using the Publisher API.

Graphql​

The quickest way to start getting events is using the GraphQL API. Below is an example request:

curl -sSL 'http://localhost:3000/auditlog/enterprise/v1/graphql' \
  -H 'Authorization: token=<YOUR_ENTERPRISE_TOKEN>' \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "variables": {
    "before": "",
    "last": 3,
    "query": "action:document.edit received:2017-11-01,2017-12-01"
  },
  "query": "query Search($query: String!, $last: Int, $before: String) { search(query: $query, last: $last, before: $before) { totalCount pageInfo { hasPreviousPage } edges { cursor node { id action crud created actor { name }}}}}"
}'

There are five things to pay attention to here:

  • We send our Enterpise API Token in a header of the form Authorization: token=...
  • variables.last is the number of events we're requesting, in this case we only want the last 3 events
  • variables.query is a free-text or structured search query, as you'd use in The Embedded Viewer.
  • variables.before allows us to specify a cursor for paging through events. Since we just want the most recent events, we'll leave this blank for now.
  • In the query field, we describe the structure and parameters of the GraphQL query.

The response will look something like

{
  "data": {
    "search": {
      "edges": [
        {
          "cursor": "MTUxMDg3MjgwNzAxMyxmMzc4MDNkZDdlOTY0NmUzYTRkZjQyZjdiNGUzOWRjMQ==",
          "node": {
            "action": "license.update",
            "actor": {
              "name": "[email protected]"
            },
            "created": "2017-11-16T22:53:27Z",
            "crud": "u",
            "id": "f37803dd7e9646e3a4df42f7b4e39dc1"
          }
        },
        {
          "cursor": "MTUxMDg3Mjc5ODUyNiwyZWFiYzA2NDI5NTc0YWEzOWNmNmI4MWYxNTQ1NzFlMQ==",
          "node": {
            "action": "license.update",
            "actor": {
              "name": "[email protected]"
            },
            "created": "2017-11-16T22:53:18Z",
            "crud": "u",
            "id": "2eabc06429574aa39cf6b81f154571e1"
          }
        },
        {
          "cursor": "MTUxMDg2Nzc3MzMxNiw5Y2M2NTM3ZGRjZTk0ZGEyODI0NTA4ZTc4M2EzOGRjNQ==",
          "node": {
            "action": "application.branding.update",
            "actor": {
              "name": "[email protected]"
            },
            "created": "2017-11-16T21:29:33Z",
            "crud": "u",
            "id": "9cc6537ddce94da2824508e783a38dc5"
          }
        }
      ],
      "pageInfo": {
        "hasPreviousPage": true
      },
      "totalCount": 2411
    }
  }
}

The query itself is in the query field of the json body:

query Search($query: String!, $last: Int, $before: String) { search(query: $query, last: $last, before: $before) { totalCount pageInfo { hasPreviousPage } edges { cursor node { id action crud created actor { name }}}}}

The same query is expanded below for readability. In general use, the first few lines won't change for every request, the interesting part is under node, where you're able to select which fields you'd like to receive.

query Search($query: String!, $last: Int, $before: String) {
  search(query: $query, last: $last, before: $before) {
    totalCount
    pageInfo {
      hasPreviousPage
    }
    edges {
      cursor
      node {
        id
        action
        crud
        created
        actor {
          name
        }
      }
    }
  }
}

This example only requests a few event fields: id, action, crud, created, and actor.name, but there are many other fields available, as described in the Event Schema.

The GraphQL APIs for consuming events are specified fully in GraphQL API Guide. There are example queries and usage in the Go SDK and the Javascript SDK

Saved Searches​

The Enterprise API includes several endpoints for saving a search and maintaining a persistent cursor across search queries.

The general workflow is:

  • Create a "Saved Search" with desired query parameters
  • Create an "Active Search" from the saved search's ID
  • Use the "Pump Active Search" endpoint whenever you want to get more events from your search.
    • Pump active search will always return only the events that occurred since the last time it was queried, so it can be called as often as every few seconds, or as infrequently as every few months

Note: Saved Search functionality may not be available in all Retraced environments.

The endpoints for managing Saved Searches are described in the Enterprise API Guide. There's also an OpenAPI/Swagger specification and interactive API console.