Manage Audit Logs

Capella Operational

how-to

How to configure and manage audit logging for App Services and App Endpoints.

This page is for App Services Audit Logging. To manage Couchbase Capella Operational audits, see Manage Audits.

To work with audit logging for App Services, you must use the Capella Operational Management API.

For an overview of the Management API, see Manage Deployments with the Management API v4.0.
To get started with the Management API, see Get Started with the Management API v4.0.
To make an API call, see Make an API Call with the Management API v4.0.
For a full reference guide, see Management API v4.0 Reference.

Examples on this Page

In the examples on this page:

$ORGID is the organization ID.
$PROJECTID is the project ID.
$CLUSTERID is the cluster ID.
$TOKEN is the API key token.

The endpoints described on this page all have the same base path: /v4/organizations/{organizationId}/projects/{projectId}/clusters/{clusterId}. For clarity, this is not shown in the instructions, but it is included in the examples.

Enable and Disable App Services Audit Logs

You can enable or disable audit logs for each App Service.

Enable App Services Audit Logs

To enable audit logging for a specified App Service:

Use PUT /appservices/{appServiceId}/auditLog.
Pass the App Service ID as a path parameter.
Pass "auditEnabled": true as the request body.

This example enables audit logging for an App Service.

$APPSERVICEID is the App Service ID.

Request

curl -X PUT "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORGID/projects/$PROJECTID/clusters/$CLUSTERID/appservices/$APPSERVICEID/auditLog" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"auditEnabled": true}'

Disable App Services Audit Logs

To disable audit logging for a specified App Service:

Use PUT /appservices/{appServiceId}/auditLog.
Pass the App Service ID as a path parameter.
Pass "auditEnabled": false as the request body.

This example disables audit logging for an App Service.

$APPSERVICEID is the App Service ID.

Request

curl -X PUT "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORGID/projects/$PROJECTID/clusters/$CLUSTERID/appservices/$APPSERVICEID/auditLog" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"auditEnabled": false}'

View App Services Audit Logging Status

To view the current status of audit logging for a specified App Service:

Use GET /appservices/{appServiceId}/auditLog.
Pass the App Service ID as a path parameter.

If successful, the auditEnabled field indicates whether or not audit logging is enabled for the specified App Service.

This example views the status of audit logging for an App Service.

$APPSERVICEID is the App Service ID.

Request

curl "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORGID/projects/$PROJECTID/clusters/$CLUSTERID/appservices/$APPSERVICEID/auditLog" \
  -H "Authorization: Bearer $TOKEN"

Output

{
  "auditEnabled": true
}

Filterable Audit Log Events

To get a list of filterable audit log events for a specified App Endpoint:

Use GET /appservices/{appServiceId}/appEndpoints/{AppEndpointName}/auditLogEvents.
Pass the App Service ID and the App Endpoint name as path parameters.

If successful, the request returns list of all filterable audit log events for the App Endpoint. If a filterable audit log event is currently disabled, you can enable it by including its ID in the enabledEventIDs field of the App Endpoint audit log configuration. See Set the Configuration of App Services Audit Logs.

This example lists filterable audit log events for an App Endpoint.

$APPSERVICEID is the App Service ID.
$APPENDPOINT is the App Endpoint name.

Request

curl "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORGID/projects/$PROJECTID/clusters/$CLUSTERID/appservices/$APPSERVICEID/appEndpoints/$APPENDPOINT/auditLogEvents" \
  -H "Authorization: Bearer $TOKEN"

Output

{
  "events": {
    "53290": {
      "description": "Admin API user successfully authenticated",
      "enabled": true,
      "filterable": true,
      "name": "Admin API user authenticated"
    },
    "53292": {
      "description": "Admin API user failed to authorize",
      "enabled": true,
      "filterable": true,
      "name": "Admin API user authorization failed"
    }
  }
}

Configure App Services Audit Logs

You can enable, disable, and configure audit logging at the App Endpoint level.

View the Configuration of App Services Audit Logs

To view the current audit logging configuration for a specified App Endpoint:

Use GET /appservices/{appServiceId}/appEndpoints/{AppEndpointName}/auditLog.
Pass the App Service ID and the App Endpoint name as path parameters.

This example shows the current audit logging configuration for an App Endpoint.

$APPSERVICEID is the App Service ID.
$APPENDPOINT is the App Endpoint name.

Request

curl "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORGID/projects/$PROJECTID/clusters/$CLUSTERID/appservices/$APPSERVICEID/appEndpoints/$APPENDPOINT/auditLog" \
  -H "Authorization: Bearer $TOKEN"

Output

{
  "auditEnabled": true,
  "enabledEventIds": [
    {
      "id": 0
    }
  ],
  "disabledUsers": [
    {
      "domain": "<DOMAIN>",
      "name": "<USER>"
    }
  ],
  "disabledRoles": [
    {
      "domain": "<DOMAIN>",
      "name": "<ROLE>"
    }
  ]
}

Set the Configuration of App Services Audit Logs

To set the audit log configuration for a specified App Endpoint:

Use PUT /appservices/{appServiceId}/appEndpoints/{AppEndpointName}/auditLog.
Pass the App Service ID and the App Endpoint name as path parameters.
Pass the required audit logging settings as the request body. For details, see the request body schema.

This example sets the audit logging configuration for an App Endpoint.

$APPSERVICEID is the App Service ID.
$APPENDPOINT is the App Endpoint name.

Request

curl -X PUT "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORGID/projects/$PROJECTID/clusters/$CLUSTERID/appservices/$APPSERVICEID/appEndpoints/$APPENDPOINT/auditLog" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
  "auditEnabled": true,
  "enabledEventIds": [
    {
      "id": 0
    }
  ],
  "disabledUsers": [
    {
      "domain": "<DOMAIN>",
      "name": "<USER>"
    }
  ],
  "disabledRoles": [
    {
      "domain": "<DOMAIN>",
      "name": "<ROLE>"
    }
  ]
}'

Stream App Services Audit Logs

You can stream your App Services audit logs to an external storage (host) via a remote endpoint.

You are responsible for any third-party audit log collectors that you configure.

Configure Streaming for App Services Audit Logs

To configure audit log streaming for a specified App Service:

Use PUT /appservices/{appServiceId}/auditLogStreaming.
Pass the App Service ID as a path parameter.
Pass the required streaming configuration as the request body. For details, see the request body schema.

If you set "streamingEnabled": true in the request body, streaming starts. Similarly, if you set "streamingEnabled": false in the request body, streaming stops.

This example configures audit log streaming for an App Service.

$APPSERVICEID is the App Service ID.

Request

curl -X PUT "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORGID/projects/$PROJECTID/clusters/$CLUSTERID/appservices/$APPSERVICEID/auditLogStreaming" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
  "streamingEnabled": true,
  "disabledAppEndpoints": [
    "<APPENDPOINT>"
  ],
  "outputType": "https",
  "credentials": {
    "apiKey": "<APIKEY>",
    "url": "<HOSTURL>"
  }
}'

Pause and Resume Streaming for App Services Audit Logs

To pause audit log streaming for a specified App Service:

Use PATCH /appservices/{appServiceId}/auditLogStreaming.
Pass the App Service ID as a path parameter.
Set "path": "/streamingEnabled" and "value": false in the request body.

This example pauses audit log streaming for an App Service.

$APPSERVICEID is the App Service ID.

Request

curl -X PATCH "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORGID/projects/$PROJECTID/clusters/$CLUSTERID/appservices/$APPSERVICEID/auditLogStreaming" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
  "op": "update",
  "path": "/streamingEnabled",
  "value": false
}'

To resume audit log streaming for a specified App Service:

Use PATCH /appservices/{appServiceId}/auditLogStreaming.
Pass the App Service ID as a path parameter.
Set "path": "/streamingEnabled" and "value": true in the request body.

This example resumes audit log streaming for an App Service.

$APPSERVICEID is the App Service ID.

Request

curl -X PATCH "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORGID/projects/$PROJECTID/clusters/$CLUSTERID/appservices/$APPSERVICEID/auditLogStreaming" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
  "op": "update",
  "path": "/streamingEnabled",
  "value": true
}'

View Status of Streaming for App Services Audit Logs

To view the current state of audit log streaming for a specified App Service:

Use GET /appservices/{appServiceId}/auditLogStreaming.
Pass the App Service ID as a path parameter.

This example shows the status of audit log streaming for an App Service.

$APPSERVICEID is the App Service ID.

Request

curl "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORGID/projects/$PROJECTID/clusters/$CLUSTERID/appservices/$APPSERVICEID/auditLogStreaming" \
  -H "Authorization: Bearer $TOKEN"

Output

{
  "streamingEnabled": true,
  "logStreamingState": "enabling",
  "disabledAppEndpoints": [
    "<APPENDPOINT>"
  ],
  "outputType": "datadog"
}

Export App Services Audit Logs

When you have enabled auditing for an App Endpoint, you can export App Services audit log files to an S3 bucket.

You must create an export job to gather and prepare the audit log files for export.

When the export job has finished, you can download the compressed file from S3, using the supplied download URL. Export requests expire after 72 hours. The download URL is valid for one hour when the export request is created.

Create an App Services Audit Log Export Job

To create an audit log export job for a specified App Service:

Use POST /appservices/{appServiceId}/auditLogExports.
Pass the App Service ID as a path parameter.
Pass the start time and end time for the audit log export job in the request body.

The value for start and end must in each case be a timestamp in RFC3339 format. The start must be at least 15 minutes in the past and no more than 30 days in the past. The end must be at least 15 minutes after the start. For additional requirements, see Limitations on Export Requests.

If successful, the request returns an audit log Export ID. You can use this to get the status of an App Services audit log export job.

This example creates an audit log export job for an App Service.

$APPSERVICEID is the App Service ID.

Request

curl -X POST "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORGID/projects/$PROJECTID/clusters/$CLUSTERID/appservices/$APPSERVICEID/auditLogExports" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
  "start": "2022-09-04T00:56:07.000Z",
  "end": "2022-09-05T04:56:07.000Z"
}'

Output

{
  "exportId": "ffffffff-aaaa-1414-eeee-000000000000"
}

Get an App Services Audit Log Export Job

You need the Export ID that was returned when you created the audit log export job to get the status of an App Services audit log export job.

To get the status of an audit log export job for a specified App Service:

Use GET /appservices/{appServiceId}/auditLogExports/{auditLogExportId}.
Pass the App Service ID and the Audit Log Export ID as path parameters.

If successful, the request returns the details of the specified audit log export job.

When the export is ready, the download_id field gives a URL that you can use to download the exported audit log.

This example gets the status of an audit log export job for an App Service.

$APPSERVICEID is the App Service ID.
$EXPORTID is the Audit Log Export ID.

Request

curl "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORGID/projects/$PROJECTID/clusters/$CLUSTERID/appservices/$APPSERVICEID/auditLogExports/$EXPORTID" \
  -H "Authorization: Bearer $TOKEN"

Output

{
  "id": "920e7b93-28c7-421b-993b-9fffecfd3598",
  "download_id": "https://cb-audit-logs-333d2ad2-1408-405e-9995-XXXX.s3.us-east-1.amazonaws.com/export/app-service-audit-logs-XXXX-from-2024-07-06-to-2024-08-05.tar.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256&X",
  "download_expires": "2024-08-08T13:43:48.420487299Z",
  "status": "Ready",
  "appServiceId": "01071798-23e5-4ec6-b814-13bebef70572",
  "tenantId": "333d2ad2-1408-405e-9995-68338d20ab5c",
  "clusterId": "71dd1cb2-34ac-43ae-a503-b2a9202f02d4",
  "createdByUserID": "d4fa667c-206a-4916-9a24-3a03c2ec5771",
  "upsertedByUserID": "",
  "createdAt": "2024-08-05T13:43:45.998790923Z",
  "upsertedAt": "0001-01-01T00:00:00Z",
  "modifiedByUserID": "d4fa667c-206a-4916-9a24-3a03c2ec5771",
  "modifiedAt": "2024-08-05T13:43:48.420521466Z",
  "version": 3
}

List App Services Audit Log Export Jobs

To get a list of all audit log export jobs for a specified App Service:

Use GET /appservices/{appServiceId}/auditLogExports.
Pass the App Service ID as a path parameter.

If successful, the request returns an array of all the audit log export jobs for the specified App Service.

For each audit log export job, when the export is ready, the download_id field gives a URL that you can use to download the exported audit log.

This example gets the status of all audit log export jobs for an App Service.

$APPSERVICEID is the App Service ID.

Request

curl "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORGID/projects/$PROJECTID/clusters/$CLUSTERID/appservices/$APPSERVICEID/auditLogExports" \
  -H "Authorization: Bearer $TOKEN"

Output

{
  "data": [
    {
      "id": "920e7b93-28c7-421b-993b-9fffecfd3598",
      "download_id": "https://cb-audit-logs-333d2ad2-1408-405e-9995-XXXX.s3.us-east-1.amazonaws.com/export/app-service-audit-logs-XXXX-from-2024-07-06-to-2024-08-05.tar.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256&X",
      "download_expires": "2024-08-08T13:43:48.420487299Z",
      "status": "Ready",
      "appServiceId": "01071798-23e5-4ec6-b814-13bebef70572",
      "tenantId": "333d2ad2-1408-405e-9995-68338d20ab5c",
      "clusterId": "71dd1cb2-34ac-43ae-a503-b2a9202f02d4",
      "createdByUserID": "d4fa667c-206a-4916-9a24-3a03c2ec5771",
      "upsertedByUserID": "",
      "createdAt": "2024-08-05T13:43:45.998790923Z",
      "upsertedAt": "0001-01-01T00:00:00Z",
      "modifiedByUserID": "d4fa667c-206a-4916-9a24-3a03c2ec5771",
      "modifiedAt": "2024-08-05T13:43:48.420521466Z",
      "version": 3
    }
  ],
  "cursor": {
    // ...
  }
}

Manage Audit Logs

Examples on this Page

Enable and Disable App Services Audit Logs

Enable App Services Audit Logs

Disable App Services Audit Logs

View App Services Audit Logging Status

Filterable Audit Log Events

Configure App Services Audit Logs

View the Configuration of App Services Audit Logs

Set the Configuration of App Services Audit Logs

Stream App Services Audit Logs

Configure Streaming for App Services Audit Logs

Pause and Resume Streaming for App Services Audit Logs

View Status of Streaming for App Services Audit Logs

Export App Services Audit Logs

Create an App Services Audit Log Export Job

Get an App Services Audit Log Export Job

List App Services Audit Log Export Jobs

See Also