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
.
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.