How to Create an Audit Logs Subscription

An audit logs subscription exports your account's activity logs to an immutable, read-only bucket on Vultr Object Storage, retaining them for a retention period you can configure and increase at any time, up to a maximum of 3,653 days (10 years). This extends log retention beyond the standard 30-day window covered by the List Logs endpoint. An account can have only one audit logs subscription.

This guide explains how to create an audit logs subscription using the Vultr API.

1. Send a GET request to the List Audit Logs Clusters endpoint to find a cluster_id for your target location.

   console Copy

   $ curl "https://api.vultr.com/v2/logs/audit-logs/clusters" \
       -X GET \
       -H "Authorization: Bearer ${VULTR_API_KEY}"
   

   Explain Code

   Note the id of your target cluster.

2. Send a POST request to the Create Audit Logs Subscription endpoint to create the subscription. Replace CLUSTER-ID with the id from the previous step, SUBSCRIPTION-LABEL with a label to identify the subscription, and EXPIRATION-DAYS with the number of days to retain logs (up to 3,653 days, or 10 years).

   console Copy

   $ curl "https://api.vultr.com/v2/logs/audit-logs" \
       -X POST \
       -H "Authorization: Bearer ${VULTR_API_KEY}" \
       -H "Content-Type: application/json" \
       --data '{
           "cluster_id": CLUSTER-ID,
           "label": "SUBSCRIPTION-LABEL",
           "expiration_days": EXPIRATION-DAYS
       }'
   

   Explain Code

   A successful request returns an HTTP 201 Created response with the subscription details, including id, sub_status, and storage_status. Note the id for future operations.

   Note

   The underlying object storage takes about a minute to activate after the subscription is created. During this time, storage_status shows pending and the s3_access_key/s3_secret_key fields are empty. After storage_status shows active, the access key and secret are populated and logs begin transferring to the bucket in 15-minute intervals.

3. Send a GET request to the Get Audit Logs Subscription endpoint to verify that storage_status has changed to active.

   console Copy

   $ curl "https://api.vultr.com/v2/logs/audit-logs/{subscription-id}" \
       -X GET \
       -H "Authorization: Bearer ${VULTR_API_KEY}"
   

   Explain Code

   After it becomes active, the response includes s3_hostname, s3_access_key, s3_secret_key, and bucket_name for connecting to the bucket with an S3-compatible client.

   Note

   Treat the s3_access_key and s3_secret_key as credentials. The access key is read-only, so it cannot write to or delete objects in the bucket, which keeps exported logs immutable.