Skip to main content

Secure Audit Log API Reference

The Secure Audit Log API is designed for recording a trail of application-based user activity in a scalable, tamper-proof log.

Base URL

audit.<csp>.<region>.pangea.cloud

post/v1/log
curl -sSLX POST 'https://audit.aws.us.pangea.cloud/v1/log' \
-H 'Authorization: Bearer <your_token>' \
-H 'Content-Type: application/json' \
-d '{}'

Response

Log an entry

POST
https://audit.aws.us.pangea.cloud/v1/log

Create a log entry in the Secure Audit Log.

required parameters

object

A structured record describing that <actor> did <action> on <target> changing it from <old> to <new> and the operation was <status>, and/or a free-form <message>.

string

A free form text field describing the event.

  • maxLength: 32,766
string

Config ID. Can be found at the top of the Secure Audit Log dashboard.

object

A structured record describing that <actor> did <action> on <target> changing it from <old> to <new> and the operation was <status>, and/or a free-form <message>.

string

An identifier for who the audit record is about.

  • maxLength: 128
string

What action was performed on a record.

  • maxLength: 32
string

The value of a record after it was changed.

  • maxLength: 32,766
string

The value of a record before it was changed.

  • maxLength: 32,766
string

The source of a record.

  • maxLength: 128
string

The status or result of the event.

  • maxLength: 32
string

An identifier for what the audit record is about.

  • maxLength: 128
string

An optional client-supplied tenant_id.

  • maxLength: 128
string (date-time)

An optional client-supplied timestamp.

  • maxLength: 128
string

This is the unpublished root hash that was returned from the last log API call that was made. If the user does not provide prev_root, the consistency proof from the last known unpublished root will be provided.

string

The base64-encoded ed25519 public key used for the signature, if one is provided

  • maxLength: 256
string

This is the signature of the hash of the canonicalized event that can be verified with the public key provided in the public_key field. Signatures cannot be used with the redaction feature turned on. If redaction is required, the user needs to perform redaction before computing the signature that is to be sent with the message. The SDK facilitates this for users.

  • maxLength: 256
boolean
(default: false)

If true, be verbose in the response; include all the data stored, creation time and proofs for the new event (both for membership and consistency)

object

Pangea standard response schema

object
object

The sealed envelope containing the event that was logged. Includes event metadata such as optional client-side signature details and server-added timestamps.

string

The hash of the event data.

  • minLength: 64

  • maxLength: 64

string

The current unpublished root.

string

A proof for verifying that the buffer_root contains the received event

array<string>

If prev_buffer_root was present in the request, this proof verifies that the new unpublished root is a continuation of prev_unpublished_root

string

A unique identifier assigned to each request made to the API. It is used to track and identify a specific request and its associated data. The request_id can be helpful for troubleshooting, auditing, and tracing the flow of requests within the system. It allows users to reference and retrieve information related to a particular request, such as the response, parameters, and raw data associated with that specific request.

"request_id":"prq_x6fdiizbon6j3bsdvnpmwxsz2aan7fqd"
string

The timestamp indicates the exact moment when a request is made to the API. It represents the date and time at which the request was initiated by the client. The request_time is useful for tracking and analyzing the timing of requests, measuring response times, and monitoring performance metrics. It allows users to determine the duration between the request initiation and the corresponding response, aiding in the assessment of API performance and latency.

"request_time":"2022-09-21T17:24:33.105Z"
string

Duration it takes for the API to process a request and generate a response. It represents the elapsed time from when the request is received by the API to when the corresponding response is returned to the client.

"response_time":"2022-09-21T17:24:34.007Z"
string

It represents the status or outcome of the API request made for IP information. It indicates the current state or condition of the request and provides information on the success or failure of the request.

"status":"success"
string

Provides a concise and brief overview of the purpose or primary objective of the API endpoint. It serves as a high-level summary or description of the functionality or feature offered by the endpoint.

post/v1/search
curl -sSLX POST 'https://audit.aws.us.pangea.cloud/v1/search' \
-H 'Authorization: Bearer <your_token>' \
-H 'Content-Type: application/json' \
-d '{}'

Response

Search the log

POST
https://audit.aws.us.pangea.cloud/v1/search

Search the Secure Audit Log.

fields

string

Natural search string; a space-separated list of case-sensitive values used to search for records, which includes the optional <field>: prefix to limit the search to a specific field. Values with a space can be enclosed in double-quote (") characters:

  • "search text": any field contains "search text"
  • actor:"Jane Doe": the actor field contains "Jane Doe"
  • actor:alice target:bob sent: actor contains "alice", target contains "bob", and any field contains "sent".

The following optional prefixes are supported: action:, actor:, message:, new:, old:, source:, status:, target:.

string

Config ID. Can be found at the top of the Secure Audit Log dashboard.

The end of the time range to perform the search on. All records up to the latest if left out.

  • maxLength: 128
integer

Maximum number of results to return.

  • minimum: 1

  • maximum: 10,000

boolean
(default: true)

If true, include the root hash of the tree and the membership proof for each record.

integer

Number of audit records to include from the first page of the results.

string

Specify the sort order of the response.

string

Name of column to sort the results by.

object

A list of keys to restrict the search results to. Useful for partitioning data available to the query string.

array<string>

A list of actors to restrict the search to.

array<string>

A list of actions to restrict the search to.

array<string>

A list of sources to restrict the search to.

array<string>

A list of statuses to restrict the search to.

array<string>

A list of targets to restrict the search to.

array<string>

A list of tenant_ids to restrict the search to.

The start of the time range to perform the search on.

  • maxLength: 128
object

Pangea standard response schema

object
integer

The total number of events that were returned by the search.

array<object>

A list of matching audit event results.

object

An audit record returned by a search operation

object

A structured record describing that <actor> did <action> on <target> changing it from <old> to <new> and the operation was <status>, and/or a free-form <message>.

string

An identifier for who the audit record is about.

  • maxLength: 128
string

What action was performed on a record.

  • maxLength: 32
string

A free form text field describing the event.

  • maxLength: 32,766
string

The value of a record after it was changed.

  • maxLength: 32,766
string

The value of a record before it was changed.

  • maxLength: 32,766
string

The source of a record.

  • maxLength: 128
string

The status or result of the event.

  • maxLength: 32
string

An identifier for what the audit record is about.

  • maxLength: 128
string

An optional client-supplied tenant_id.

  • maxLength: 128
string (date-time)

An optional client-supplied timestamp.

  • maxLength: 128
array<object>

A list of errors (if any) encountered when processing the event. A non-empty array indicates the client had sent a malformed event.

string

A description of the detected error/problem with the original event.

string

The original JSON field where the error was detected.

The original JSON value (may be truncated.)

string (date-time)

A Pangea provided timestamp of when the event was received.

string

This is the signature of the hash of the canonicalized event that can be verified with the public key provided in the public_key field. Signatures cannot be used with the redaction feature turned on. If redaction is required, the user needs to perform redaction before computing the signature that is to be sent with the message. The SDK facilitates this for users.

  • maxLength: 256
string

The base64-encoded ed25519 public key used for the signature, if one is provided

  • maxLength: 256
string

A cryptographic proof that the record has been persisted in the log

string

The record's hash

  • minLength: 64

  • maxLength: 64

boolean

If true, a root has been published after this event. If false, there is no published root for this event

integer

The index of the leaf of the Merkle Tree where this record was inserted or null if published=false

string (date-time)

The time when the results will no longer be available to page through via the results API.

string

Identifier to supply to search_results API to fetch/paginate through search results.

object

A root of a Merkle Tree

integer

The size of the tree (the number of records)

  • minimum: 1
string

The root hash

  • minLength: 64

  • maxLength: 64

string (date-time)

The date/time when this root was published

string (uri)

The URL where this root has been published

string

The name of the Merkle Tree

string

Consistency proof to verify that this root is a continuation of the previous one

object

A root of a Merkle Tree that was not published yet

integer

The size of the tree (the number of records)

  • minimum: 1
string

The root hash

  • minLength: 64

  • maxLength: 64

string

The name of the Merkle Tree

string

Consistency proof to verify that this root is a continuation of the previous one

string

A unique identifier assigned to each request made to the API. It is used to track and identify a specific request and its associated data. The request_id can be helpful for troubleshooting, auditing, and tracing the flow of requests within the system. It allows users to reference and retrieve information related to a particular request, such as the response, parameters, and raw data associated with that specific request.

"request_id":"prq_x6fdiizbon6j3bsdvnpmwxsz2aan7fqd"
string

The timestamp indicates the exact moment when a request is made to the API. It represents the date and time at which the request was initiated by the client. The request_time is useful for tracking and analyzing the timing of requests, measuring response times, and monitoring performance metrics. It allows users to determine the duration between the request initiation and the corresponding response, aiding in the assessment of API performance and latency.

"request_time":"2022-09-21T17:24:33.105Z"
string

Duration it takes for the API to process a request and generate a response. It represents the elapsed time from when the request is received by the API to when the corresponding response is returned to the client.

"response_time":"2022-09-21T17:24:34.007Z"
string

It represents the status or outcome of the API request made for IP information. It indicates the current state or condition of the request and provides information on the success or failure of the request.

"status":"success"
string

Provides a concise and brief overview of the purpose or primary objective of the API endpoint. It serves as a high-level summary or description of the functionality or feature offered by the endpoint.

post/v1/results
curl -sSLX POST 'https://audit.aws.us.pangea.cloud/v1/results' \
-H 'Authorization: Bearer <your_token>' \
-H 'Content-Type: application/json' \
-d '{}'

Response

Search results

POST
https://audit.aws.us.pangea.cloud/v1/results

Page through results from a previous search.

required parameters

string

A search results identifier returned by the search call.

string

Config ID. Can be found at the top of the Secure Audit Log dashboard.

integer

Number of audit records to include in a single set of results.

integer

Offset from the start of the result set to start returning results from.

object

Pangea standard response schema

object
integer

The total number of results returned by the search.

array<object>

A list of matching audit records.

object

An audit record returned by a search operation

object

A structured record describing that <actor> did <action> on <target> changing it from <old> to <new> and the operation was <status>, and/or a free-form <message>.

string

An identifier for who the audit record is about.

  • maxLength: 128
string

What action was performed on a record.

  • maxLength: 32
string

A free form text field describing the event.

  • maxLength: 32,766
string

The value of a record after it was changed.

  • maxLength: 32,766
string

The value of a record before it was changed.

  • maxLength: 32,766
string

The source of a record.

  • maxLength: 128
string

The status or result of the event.

  • maxLength: 32
string

An identifier for what the audit record is about.

  • maxLength: 128
string

An optional client-supplied tenant_id.

  • maxLength: 128
string (date-time)

An optional client-supplied timestamp.

  • maxLength: 128
array<object>

A list of errors (if any) encountered when processing the event. A non-empty array indicates the client had sent a malformed event.

string

A description of the detected error/problem with the original event.

string

The original JSON field where the error was detected.

The original JSON value (may be truncated.)

string (date-time)

A Pangea provided timestamp of when the event was received.

string

This is the signature of the hash of the canonicalized event that can be verified with the public key provided in the public_key field. Signatures cannot be used with the redaction feature turned on. If redaction is required, the user needs to perform redaction before computing the signature that is to be sent with the message. The SDK facilitates this for users.

  • maxLength: 256
string

The base64-encoded ed25519 public key used for the signature, if one is provided

  • maxLength: 256
string

A cryptographic proof that the record has been persisted in the log

string

The record's hash

  • minLength: 64

  • maxLength: 64

boolean

If true, a root has been published after this event. If false, there is no published root for this event

integer

The index of the leaf of the Merkle Tree where this record was inserted or null if published=false

object

A root of a Merkle Tree

integer

The size of the tree (the number of records)

  • minimum: 1
string

The root hash

  • minLength: 64

  • maxLength: 64

string (date-time)

The date/time when this root was published

string (uri)

The URL where this root has been published

string

The name of the Merkle Tree

string

Consistency proof to verify that this root is a continuation of the previous one

object

A root of a Merkle Tree that was not published yet

integer

The size of the tree (the number of records)

  • minimum: 1
string

The root hash

  • minLength: 64

  • maxLength: 64

string

The name of the Merkle Tree

string

Consistency proof to verify that this root is a continuation of the previous one

string

A unique identifier assigned to each request made to the API. It is used to track and identify a specific request and its associated data. The request_id can be helpful for troubleshooting, auditing, and tracing the flow of requests within the system. It allows users to reference and retrieve information related to a particular request, such as the response, parameters, and raw data associated with that specific request.

"request_id":"prq_x6fdiizbon6j3bsdvnpmwxsz2aan7fqd"
string

The timestamp indicates the exact moment when a request is made to the API. It represents the date and time at which the request was initiated by the client. The request_time is useful for tracking and analyzing the timing of requests, measuring response times, and monitoring performance metrics. It allows users to determine the duration between the request initiation and the corresponding response, aiding in the assessment of API performance and latency.

"request_time":"2022-09-21T17:24:33.105Z"
string

Duration it takes for the API to process a request and generate a response. It represents the elapsed time from when the request is received by the API to when the corresponding response is returned to the client.

"response_time":"2022-09-21T17:24:34.007Z"
string

It represents the status or outcome of the API request made for IP information. It indicates the current state or condition of the request and provides information on the success or failure of the request.

"status":"success"
string

Provides a concise and brief overview of the purpose or primary objective of the API endpoint. It serves as a high-level summary or description of the functionality or feature offered by the endpoint.

post/v1/root
curl -sSLX POST 'https://audit.aws.us.pangea.cloud/v1/root' \
-H 'Authorization: Bearer <your_token>' \
-H 'Content-Type: application/json' \
-d '{}'

Response

Tamperproof Verification

POST
https://audit.aws.us.pangea.cloud/v1/root

Return current root hash and consistency proof.

fields

string

Config ID. Can be found at the top of the Secure Audit Log dashboard.

integer

The size of the tree (the number of records)

  • minimum: 1
object

Pangea standard response schema

object

A root of a Merkle Tree

integer

The size of the tree (the number of records)

  • minimum: 1
string

The root hash

  • minLength: 64

  • maxLength: 64

string (date-time)

The date/time when this root was published

string (uri)

The URL where this root has been published

string

The name of the Merkle Tree

string

Consistency proof to verify that this root is a continuation of the previous one

string

A unique identifier assigned to each request made to the API. It is used to track and identify a specific request and its associated data. The request_id can be helpful for troubleshooting, auditing, and tracing the flow of requests within the system. It allows users to reference and retrieve information related to a particular request, such as the response, parameters, and raw data associated with that specific request.

"request_id":"prq_x6fdiizbon6j3bsdvnpmwxsz2aan7fqd"
string

The timestamp indicates the exact moment when a request is made to the API. It represents the date and time at which the request was initiated by the client. The request_time is useful for tracking and analyzing the timing of requests, measuring response times, and monitoring performance metrics. It allows users to determine the duration between the request initiation and the corresponding response, aiding in the assessment of API performance and latency.

"request_time":"2022-09-21T17:24:33.105Z"
string

Duration it takes for the API to process a request and generate a response. It represents the elapsed time from when the request is received by the API to when the corresponding response is returned to the client.

"response_time":"2022-09-21T17:24:34.007Z"
string

It represents the status or outcome of the API request made for IP information. It indicates the current state or condition of the request and provides information on the success or failure of the request.

"status":"success"
string

Provides a concise and brief overview of the purpose or primary objective of the API endpoint. It serves as a high-level summary or description of the functionality or feature offered by the endpoint.

post/v2/log
curl -sSLX POST 'https://audit.aws.us.pangea.cloud/v2/log' \
-H 'Authorization: Bearer <your_token>' \
-H 'Content-Type: application/json' \
-d '{}'

Response

Log multiple entries

POST
https://audit.aws.us.pangea.cloud/v2/log

Create multiple log entries in the Secure Audit Log.

required parameters

array<object>
  • minItems: 1

  • maxItems: 1,000

object

A structured record describing that <actor> did <action> on <target> changing it from <old> to <new> and the operation was <status>, and/or a free-form <message>.

string

An identifier for who the audit record is about.

  • maxLength: 128
string

What action was performed on a record.

  • maxLength: 32
string

A free form text field describing the event.

  • maxLength: 32,766
string

The value of a record after it was changed.

  • maxLength: 32,766
string

The value of a record before it was changed.

  • maxLength: 32,766
string

The source of a record.

  • maxLength: 128
string

The status or result of the event.

  • maxLength: 32
string

An identifier for what the audit record is about.

  • maxLength: 128
string

An optional client-supplied tenant_id.

  • maxLength: 128
string (date-time)

An optional client-supplied timestamp.

  • maxLength: 128
string

The base64-encoded ed25519 public key used for the signature, if one is provided

  • maxLength: 256
string

This is the signature of the hash of the canonicalized event that can be verified with the public key provided in the public_key field. Signatures cannot be used with the redaction feature turned on. If redaction is required, the user needs to perform redaction before computing the signature that is to be sent with the message. The SDK facilitates this for users.

  • maxLength: 256
string

Config ID. Can be found at the top of the Secure Audit Log dashboard.

boolean
(default: false)

If true, be verbose in the response; include all the data stored, creation time and proofs for the new event (both for membership and consistency)

object

Pangea standard response schema

object
array<object>
object

The sealed envelope containing the event that was logged. Includes event metadata such as optional client-side signature details and server-added timestamps.

string

The hash of the event data.

  • minLength: 64

  • maxLength: 64

string

The current unpublished root.

string

A proof for verifying that the buffer_root contains the received event

array<string>

If prev_buffer_root was present in the request, this proof verifies that the new unpublished root is a continuation of prev_unpublished_root

string

A unique identifier assigned to each request made to the API. It is used to track and identify a specific request and its associated data. The request_id can be helpful for troubleshooting, auditing, and tracing the flow of requests within the system. It allows users to reference and retrieve information related to a particular request, such as the response, parameters, and raw data associated with that specific request.

"request_id":"prq_x6fdiizbon6j3bsdvnpmwxsz2aan7fqd"
string

The timestamp indicates the exact moment when a request is made to the API. It represents the date and time at which the request was initiated by the client. The request_time is useful for tracking and analyzing the timing of requests, measuring response times, and monitoring performance metrics. It allows users to determine the duration between the request initiation and the corresponding response, aiding in the assessment of API performance and latency.

"request_time":"2022-09-21T17:24:33.105Z"
string

Duration it takes for the API to process a request and generate a response. It represents the elapsed time from when the request is received by the API to when the corresponding response is returned to the client.

"response_time":"2022-09-21T17:24:34.007Z"
string

It represents the status or outcome of the API request made for IP information. It indicates the current state or condition of the request and provides information on the success or failure of the request.

"status":"success"
string

Provides a concise and brief overview of the purpose or primary objective of the API endpoint. It serves as a high-level summary or description of the functionality or feature offered by the endpoint.

post/v2/log_async
curl -sSLX POST 'https://audit.aws.us.pangea.cloud/v2/log_async' \
-H 'Authorization: Bearer <your_token>' \
-H 'Content-Type: application/json' \
-d '{}'

Response

Log multiple entries asynchronously

POST
https://audit.aws.us.pangea.cloud/v2/log_async

Asynchronously create multiple log entries in the Secure Audit Log.

required parameters

array<object>
  • minItems: 1

  • maxItems: 1,000

object

A structured record describing that <actor> did <action> on <target> changing it from <old> to <new> and the operation was <status>, and/or a free-form <message>.

string

An identifier for who the audit record is about.

  • maxLength: 128
string

What action was performed on a record.

  • maxLength: 32
string

A free form text field describing the event.

  • maxLength: 32,766
string

The value of a record after it was changed.

  • maxLength: 32,766
string

The value of a record before it was changed.

  • maxLength: 32,766
string

The source of a record.

  • maxLength: 128
string

The status or result of the event.

  • maxLength: 32
string

An identifier for what the audit record is about.

  • maxLength: 128
string

An optional client-supplied tenant_id.

  • maxLength: 128
string (date-time)

An optional client-supplied timestamp.

  • maxLength: 128
string

The base64-encoded ed25519 public key used for the signature, if one is provided

  • maxLength: 256
string

This is the signature of the hash of the canonicalized event that can be verified with the public key provided in the public_key field. Signatures cannot be used with the redaction feature turned on. If redaction is required, the user needs to perform redaction before computing the signature that is to be sent with the message. The SDK facilitates this for users.

  • maxLength: 256
string

Config ID. Can be found at the top of the Secure Audit Log dashboard.

boolean
(default: false)

If true, be verbose in the response; include all the data stored, creation time and proofs for the new event (both for membership and consistency)

object

Pangea standard response schema

object
integer

TTL from now until which results are stored for retrieval.

integer

Number of retry counts performed so far to fetch the results.

string

The location to check results of the asynchronous request.

string

A unique identifier assigned to each request made to the API. It is used to track and identify a specific request and its associated data. The request_id can be helpful for troubleshooting, auditing, and tracing the flow of requests within the system. It allows users to reference and retrieve information related to a particular request, such as the response, parameters, and raw data associated with that specific request.

"request_id":"prq_x6fdiizbon6j3bsdvnpmwxsz2aan7fqd"
string

The timestamp indicates the exact moment when a request is made to the API. It represents the date and time at which the request was initiated by the client. The request_time is useful for tracking and analyzing the timing of requests, measuring response times, and monitoring performance metrics. It allows users to determine the duration between the request initiation and the corresponding response, aiding in the assessment of API performance and latency.

"request_time":"2022-09-21T17:24:33.105Z"
string

Duration it takes for the API to process a request and generate a response. It represents the elapsed time from when the request is received by the API to when the corresponding response is returned to the client.

"response_time":"2022-09-21T17:24:34.007Z"
string

It represents the status or outcome of the API request made for IP information. It indicates the current state or condition of the request and provides information on the success or failure of the request.

"status":"success"
string

Provides a concise and brief overview of the purpose or primary objective of the API endpoint. It serves as a high-level summary or description of the functionality or feature offered by the endpoint.

post/v1/download_results
curl -sSLX POST 'https://audit.aws.us.pangea.cloud/v1/download_results' \
-H 'Authorization: Bearer <your_token>' \
-H 'Content-Type: application/json' \
-d '{}'

Response

Download search results

POST
https://audit.aws.us.pangea.cloud/v1/download_results

Get all search results as a compressed (gzip) CSV file.

fields

string

ID returned by the search API.

string
(default: "json")

ID returned by the search API.

object

Pangea standard response schema

object
string

URL where search results can be downloaded

string

A unique identifier assigned to each request made to the API. It is used to track and identify a specific request and its associated data. The request_id can be helpful for troubleshooting, auditing, and tracing the flow of requests within the system. It allows users to reference and retrieve information related to a particular request, such as the response, parameters, and raw data associated with that specific request.

"request_id":"prq_x6fdiizbon6j3bsdvnpmwxsz2aan7fqd"
string

The timestamp indicates the exact moment when a request is made to the API. It represents the date and time at which the request was initiated by the client. The request_time is useful for tracking and analyzing the timing of requests, measuring response times, and monitoring performance metrics. It allows users to determine the duration between the request initiation and the corresponding response, aiding in the assessment of API performance and latency.

"request_time":"2022-09-21T17:24:33.105Z"
string

Duration it takes for the API to process a request and generate a response. It represents the elapsed time from when the request is received by the API to when the corresponding response is returned to the client.

"response_time":"2022-09-21T17:24:34.007Z"
string

It represents the status or outcome of the API request made for IP information. It indicates the current state or condition of the request and provides information on the success or failure of the request.

"status":"success"
string

Provides a concise and brief overview of the purpose or primary objective of the API endpoint. It serves as a high-level summary or description of the functionality or feature offered by the endpoint.

Status Codes
StatusStatus CodeDescription
TreeNotFound200

A tree has not been built for proofs. This is likely due to a lack of audit messages ingested.

BadOffset400

The offset provided is invalid or out of range.

ForwardingError400

Forwarder has experienced an error while forwarding messages

NoForwarderConfigured400

Testing a forwarder requires a forwarder to be configured

ForbiddenFieldValue403

A field value was supplied that is not allowed by the token's field restrictions.

Was this article helpful?

Contact us