Introduction

AuditAPI provides a RESTful API consisting of simple and predictable URLs to create and access data. All requests should be made over HTTPS. All request and response bodies, including errors, are encoded in JSON.

Authentication

# HTTP Basic Authentication
curl https://api.auditapi.com/v1/events \
  -u $KEY:

# Bearer Authentication
curl https://api.auditapi.com/v1/events \
  -H 'Authorization: Bearer $KEY'

require 'auditapi'
AuditAPI.api_key = 'abc123abc123abc123abc123abc123ab'

Authentication is done via API key. API keys are provisioned per-project and can be viewed in your project settings.

Requests are authenticated using HTTP Basic Auth. Provide your API key as the basic auth username. You do not need to provide a password.

Alternatively, you can also pass your API key as a bearer token in an Authorization header.

Your API keys carry many privileges, so be sure to keep them secure. Do not share your API keys in publicly accessible areas such as GitHub, client-side code, etc.

Errors

AuditAPI uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and 5xx range indicate an error with AuditAPI's servers.

HTTP Status Codes

Code	Title	Description
200	OK	The request was successful
400	Bad request	The request was malformed and could not be parsed
401	Unauthorized	Your API key is missing or invalid
402	Over quota	You've exceeded your plan quota
404	Not found	The requested resource does not exist
413	Payload too large	The request payload is too large
422	Validation error	A validation error occurred
429	Too many requests	The rate limit was exceeded
50x	Internal Server error	An error occurred with our API

Pagination

AuditAPI utilizes cursor-based pagination via the starting_after and ending_before parameters. Both parameters take an existing object ID and return objects in reverse chronological order. The ending_before parameter returns objects listed before the named object. The starting_after parameter returns objects listed after the named object. If both parameters are provided, only ending_before is used.

limit is also supported to limit the number of returned objects. By default, 10 objects are returned. You can request up to 100 objects.

Events

Audit logs consist of events. In AuditAPI, you create Event objects. You can retrieve individual events, list all events, or search for specific events. Events are identified by a unique, random ID.

Event object

Attributes

Event object

{
  "id": "289e11ff-d84b-446d-92ef-faf79fb4cb2f",
  "object": "event",
  "timestamp": "2019-12-25T22:57:24Z",
  "payload": {
    "action": "account.created",
    "account_id": 1234,
    "user_id": 5678
  }
}

Parameter	Type	Description
id	string	Unique identifier for the object.
object	string	String representing the object’s type.
timestamp	timestamp	Time at which the object was created, in ISO 8601 format.
payload	hash	Hash containing data associated with the object.

Create an event

POST /v1/events

curl -X POST https://api.auditapi.com/v1/events \
  -u $KEY: \
  -H 'Content-Type: application/json' \
  -d '{
    "timestamp": "2019-12-25T22:57:24Z",
    "action": "account.created",
    "account_id": 1234,
    "user_id": 5678
  }'

AuditAPI::Event.create({
  action: 'account.created',
  account_id: 1234,
  user_id: 5678
})

Response

{
  "id": "289e11ff-d84b-446d-92ef-faf79fb4cb2f",
  "object": "event"
}

Arguments

body required
The JSON-formatted payload to be persisted.

timestamp optional
The timestamp for when the event occurred within your app. If timestamp isn't specified, we use the time that the event was received by our systems. timestamp must be ISO 8601 formatted or it will be ignored. Include it within the JSON request body.

Returns

A dictionary with an id property that is the identifier for the newly created event.

Note: The submitted payload is being asynchronously processed. To validate persistence, retrieve the event using the returned id.

Retrieve an event

GET /v1/events/:id

curl https://api.auditapi.com/v1/events/289e11ff-d84b-446d-92ef-faf79fb4cb2f \
  -u $KEY:

AuditAPI::Event.retrieve('289e11ff-d84b-446d-92ef-faf79fb4cb2f')

Response

{
  "id": "289e11ff-d84b-446d-92ef-faf79fb4cb2f",
  "object": "event",
  "timestamp": "2019-12-25T22:57:24Z",
  "payload": {
    "action": "account.created",
    "account_id": 1234,
    "user_id": 5678
  }
}

Retrieves the details of an existing event.

Arguments

event id required
The identifier of the event to be retrieved.

Returns

If a valid identifier was provided, an event will be returned. Otherwise, an error will be returned.

List all events

GET /v1/events

curl https://api.auditapi.com/v1/events?limit=3 \
  -u $KEY:

AuditAPI::Event.list(limit: 1)

Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "289e11ff-d84b-446d-92ef-faf79fb4cb2f",
      "object": "event",
      "timestamp": "2019-12-25T22:57:24Z",
      "payload": {
        "action": "account.created",
        "account_id": 1234,
        "user_id": 5678
      }
    }
  ]
}

Returns a list of events, sorted by timestamp, with the most recent events appearing first.

Arguments

start_date optional
A filter on the list based on an event's timestamp field. The value must be formatted as YYYY-MM-DD.

end_date optional
A filter on the list based on an event's timestamp field. The value must be formatted as YYYY-MM-DD.

starting_after optional
A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For example, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

ending_before optional
A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For example, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

limit optional
A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

filter optional
A filter on the list based on an event's payload field. For example, to only include events with a JSON key-value of account_id: 1, include filter=account_id:1 in your request.

Returns

A dictionary with a data property that contains an array of up to limit events, starting after event starting_after. Each entry in the array is a separate event object. If no more events are available, the resulting array will be empty.

Search events

GET /v1/events/search

curl https://api.auditapi.com/v1/events/search?query=289e11ff* \
  -u $KEY:

AuditAPI::Event.search(query: '289e11ff*')

Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "289e11ff-d84b-446d-92ef-faf79fb4cb2f",
      "object": "event",
      "timestamp": "2019-12-25T22:57:24Z",
      "payload": {
        "action": "account.created",
        "account_id": 1234,
        "user_id": 5678
      }
    }
  ]
}

Returns a list of events that contain your query within their payload, sorted by timestamp, with the most recent events appearing first.

Arguments

query required
A string to query your event payload fields. Wildcards are supported by using *. For example: ?query=account.* or ?query="user upgraded account"

start_date optional
A filter on the list based on an event's timestamp field. The value must be formatted as YYYY-MM-DD.

end_date optional
A filter on the list based on an event's timestamp field. The value must be formatted as YYYY-MM-DD.

limit optional
A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

filter optional
A filter on the list based on an event's payload field. For example, to only include events with a JSON key-value of account_id: 1, include filter=account_id:1 in your request.