Skip to main content
API docs by Redocly

Auditum API (v1alpha1)

This is the specification for Auditum HTTP API.

For gRPC API, see repository.

For more information, see Usage Guide.

For any issues and feature requests, please use GitHub Issue Tracker

Projects

Project is the top-level resource in Auditum. Projects contain all other resources like Records.

A project is a logical grouping of records. Typically, a project is created for each of the applications that is being audited.

Usage Guide :: Create Project

List projects

Returns a list of projects by the provided criteria.

query Parameters
page_size
integer <int32>

The maximum number of projects to return. The service may return fewer than this value. If unspecified, at most 10 projects will be returned. The maximum value is 100; values above 100 will be coerced to 100.

page_token
string

A page token, received from a previous ListProjects call. Provide this to retrieve the subsequent page.

When paginating, all other parameters provided to ListProjects must match the call that provided the page token.

Responses

Response samples

Content type
{
  • "projects": [
    ],
  • "next_page_token": "string"
}

Create project

Creates a new project.

Request Body schema: application/json
required
object (auditumio.auditum.v1alpha1.Project)

Represents a project.

display_name
required
string

Display name of the project.

REQUIREMENTS. The value must be 3-64 characters long.

update_record_enabled
boolean

Whether to allow updating records for this project. If set, overrides the global setting. Defaults to unset.

delete_record_enabled
boolean

Whether to allow deleting records for this project. If set, overrides the global setting. Defaults to unset.

Responses

Request samples

Content type
application/json
{
  • "project": {
    }
}

Response samples

Content type
{
  • "project": {
    }
}

Get project

Returns a project by its id.

path Parameters
project_id
required
string

ID of the record to get.

Responses

Response samples

Content type
{
  • "project": {
    }
}

Update project

Updates an existing project.

path Parameters
project_id
required
string

Internal project identifier.

Request Body schema: application/json
object (Project to update.)

Project to update.

update_mask
required
string

Field mask indicating a list of fields to update. Currently supported fields:

  • display_name
  • update_record_enabled
  • delete_record_enabled Support for other fields may be added in the future.

Responses

Request samples

Content type
application/json
{
  • "project": {
    },
  • "update_mask": "string"
}

Response samples

Content type
{
  • "project": {
    }
}

Records

Record is the core resource in Auditum. Records represent audit trail records a.k.a. audit logs.

Usage Guide :: Create Records

List records

Returns a list of records by the provided criteria.

Usage Guide :: Search Records
path Parameters
project_id
required
string

ID of the project that owns the records.

query Parameters
filter.labels[string]
string

This is a request variable of the map type. The query format is "map_name[key]=value", e.g. If the map name is Age, the key type is string, and the value type is integer, the query parameter is expressed as Age["bob"]=18

filter.resource_type
string

Return records with the provided resource type.

filter.resource_id
string

Return records with the provided resource ID.

filter.operation_type
string

Return records with the provided operation type.

filter.operation_id
string

Return records with the provided operation ID.

filter.operation_time_from
string <date-time>

Return records with operation time starting from the provided time, inclusive.

filter.operation_time_to
string <date-time>

Return records with operation time up to the provided time, exclusive.

filter.actor_type
string

Return records with the provided actor type.

filter.actor_id
string

Return records with the provided actor ID.

page_size
integer <int32>

The maximum number of records to return. The service may return fewer than this value. If unspecified, at most 10 records will be returned. The maximum value is 100; values above 100 will be coerced to 100.

page_token
string

A page token, received from a previous ListRecords call. Provide this to retrieve the subsequent page.

When paginating, all other parameters provided to ListRecords must match the call that provided the page token.

Responses

Response samples

Content type
{
  • "records": [
    ],
  • "next_page_token": "string"
}

Create record

Creates a new audit record.

path Parameters
project_id
required
string

Identifier of the project the record belongs to.

Request Body schema: application/json
object (Record to create.)

Record to create.

object

Labels for the record that can be used for filtering. The labels are indexed, unlike metadata fields, which means it is possible to find records by their labels.

REQUIREMENTS. Mandatory: Keys must conform to the following regexp: [a-zA-Z0-9-_]+. Keys must be at least 1 byte in length. Configurable defaults: Keys must be at most 64 bytes in length. Values must be at most 256 bytes in length. The total size of all keys and values must be at most 2048 bytes.

EXAMPLE. In an example social website domain, records for both POST and COMMENT resources can be created with "post_id" label. This way all records related to the post and its comments can be retrieved in chronological order with one request by filtering with "post_id" label.

BEST PRACTICE.

  • Add only labels that are critical for chronological retrieval of records related to multiple resources.
  • Do not add labels for standard fields (such as resource type) as they are already available for filtering.
object (auditumio.auditum.v1alpha1.Resource)

Represents the audit record resource.

object (auditumio.auditum.v1alpha1.Operation)

Represents the audit record operation.

object (auditumio.auditum.v1alpha1.Actor)

Represents the audit record actor.

Responses

Request samples

Content type
application/json
{
  • "record": {
    }
}

Response samples

Content type
{
  • "record": {
    }
}

Get record

Returns a record by its id.

path Parameters
project_id
required
string

ID of the project that owns the record.

record_id
required
string

ID of the record to retrieve.

Responses

Response samples

Content type
{
  • "record": {
    }
}

Delete record

Deletes an existing project.

⚠️ NOTE: this operation is disabled by default and may be enabled per project or globally.

Usage Guide :: Delete Records
path Parameters
project_id
required
string

ID of the project that owns the record.

record_id
required
string

ID of the record to delete.

Responses

Response samples

Content type
{ }

Update record

Updates an existing project.

⚠️ NOTE: this operation is disabled by default and may be enabled per project or globally.

Usage Guide :: Update Records
path Parameters
project_id
required
string

Identifier of the project the record belongs to.

record_id
required
string

Internal record identifier.

Request Body schema: application/json
object (Record to update.)

Record to update.

update_mask
required
string

Field mask indicating a list of fields to update. Currently supported fields:

  • labels
  • resource
  • operation
  • actor Support for other fields may be added in the future.

Responses

Request samples

Content type
application/json
{
  • "record": {
    },
  • "update_mask": "string"
}

Response samples

Content type
{
  • "record": {
    }
}

Batch create records

Creates multiple audit records in a batch.

path Parameters
project_id
required
string

ID of the project to create records in.

Request Body schema: application/json
required
Array of objects (auditumio.auditum.v1alpha1.Record) <= 100 items

Records to create. Maximum number of records in a batch is 100.

Array (<= 100 items)
project_id
required
string

Identifier of the project the record belongs to.

object

Labels for the record that can be used for filtering. The labels are indexed, unlike metadata fields, which means it is possible to find records by their labels.

REQUIREMENTS. Mandatory: Keys must conform to the following regexp: [a-zA-Z0-9-_]+. Keys must be at least 1 byte in length. Configurable defaults: Keys must be at most 64 bytes in length. Values must be at most 256 bytes in length. The total size of all keys and values must be at most 2048 bytes.

EXAMPLE. In an example social website domain, records for both POST and COMMENT resources can be created with "post_id" label. This way all records related to the post and its comments can be retrieved in chronological order with one request by filtering with "post_id" label.

BEST PRACTICE.

  • Add only labels that are critical for chronological retrieval of records related to multiple resources.
  • Do not add labels for standard fields (such as resource type) as they are already available for filtering.
required
object (auditumio.auditum.v1alpha1.Resource)

Represents the audit record resource.

required
object (auditumio.auditum.v1alpha1.Operation)

Represents the audit record operation.

required
object (auditumio.auditum.v1alpha1.Actor)

Represents the audit record actor.

Responses

Request samples

Content type
application/json
{
  • "records": [
    ]
}

Response samples

Content type
{
  • "records": [
    ]
}