--- title: "How to use SAFE’s Audit APIs" slug: "how-to-use-safes-audit-apis" updated: 2025-04-11T06:25:17Z published: 2025-04-11T06:25:17Z canonical: "docs.safe.security/how-to-use-safes-audit-apis" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.safe.security/llms.txt > Use this file to discover all available pages before exploring further. # How to use SAFE’s Audit APIs By default, SAFE provides a downloadable audit log within the application. For details, see [Advanced Settings](https://docs.safe.security/docs/advanced). ## Overview SAFE provides the capability to access security information, which can be integrated into a customer's chosen Security Information and Event Management (SIEM) platform. This integration is facilitated through a generic interface that makes relevant information available to the target SIEM. Additionally, SAFE supports the integration process to ensure a seamless connection with the customer's platform. The logs provided will include the following details: - Timestamp - Source IP and Port - Username - Action/Activity: This may include activities such as: - Application login/logout - Modifications to integrations (initial setup, updates, testing, and starting/stopping synchronizations) - Changes to groups (creation, updates, and deletions) - Alterations in risk scenarios (creation, updates, and deletions) - Updates to any questionnaires These logs are provided in a JSON format for easy integration and readability. For customers who have purchased the "Bring Your Own Account (BYOA)" option, AWS CloudWatch logs will also be made accessible for integration into their chosen SIEM system. If the customer requires custom modifications to the generic interface for better compatibility with their SIEM, such work will be defined and agreed upon through a specific Statement of Work (SOW). This solution caters to customers seeking enhanced visibility into user actions, including login and logout activities on the SAFE platform, within their SIEM. ## Architecture ### SAFE Application Overview The following diagram illustrates the architecture of the SAFE Application, which efficiently forwards application audit logs to a CloudWatch Log Group. SIEM tools, equipped with appropriate Add-ons and Plugins, can directly retrieve these logs from the CloudWatch Log Group, facilitating streamlined integration and monitoring. ![](https://cdn.document360.io/23dc20b8-a989-48c0-8653-f1d3e4abc734/Images/Documentation/image(213).png) ### SAFE Application Workflow In the following diagram, we detail the SAFE Application's workflow for transmitting application audit logs to a CloudWatch Log Group. Simultaneously, AWS CloudTrail forwards infrastructure-level audit logs to an S3 bucket. SIEM tools can seamlessly access these logs from both CloudWatch Log Group and the S3 bucket using enhanced Add-ons and Plugins. This functionality is specifically available to Bring Your Own Account (BYOA) customers who manage their own AWS accounts for CloudTrail log ingestion. ![](https://cdn.document360.io/23dc20b8-a989-48c0-8653-f1d3e4abc734/Images/Documentation/image(214).png) ### Prerequisites - SIEM Compatibility: Ensure that the customer's SIEM tool is compatible with AWS services and can ingest logs from CloudWatch and S3, either through native integrations or using available plugins and add-ons. - IAM Role Configuration: SAFE must set up an IAM role within the AWS account with permissions to read logs from CloudWatch and S3. This role should be assumable by the SIEM tool to securely access the logs. - Network Connectivity: Verify that the customer's network infrastructure allows outbound connections to AWS services. This includes configuring firewalls and security groups to permit traffic to necessary AWS endpoints. > [!WARNING] > For customers who prefer not to have live integration with dynamic updates, scripting can be built to periodically query our APIs: > > - POST /api/v3/audit-logs/export: This API takes the number of days as a payload and returns a UUID, which must be used with the subsequent API call. > - GET /api/v3/audit-logs/export/: With the UUID, this API allows customers to retrieve data daily and dump it to an S3 or similar location for post-processing. ## GET /api/v3/users: To fetch the list of users onboarded to the SAFE One Application This API allows users to GET the list of SAFE users currently onboarded to their SAFE application. It provides important details such as the user's First Name, Last Name, Email Address, Last Login Time, and Role as part of the response. This API needs to be called for Audit Logs, as: - Audit logs represent users by their UUID (User ID column). - The user API will provide ‘uuid’ to user mapping for your reference. Note: This API is now available in Swagger as well. #### Parameters | Name | Description | | --- | --- | | page integer (query) | Pagination parameter for page number | | pagelen integer (query) | Number of items on this page, default is 10 | | searchKey string (query) | Filter users by passing different criteria | #### Example Request: | curl --location 'https://us.safeone.ai/api/v3/users' \ --header 'Authorization: Bearer {{safe-bearer-token}}' | | --- | #### Responses | Code | Description | Links | | --- | --- | --- | | 200 | User details are presented as an array of individual user object ### Response Information 1. page (Integer) - This defines the current page number 2. pagelen(Integer) - This defines the maximum number of items visible per page 3. size(Integer) - This contains the total number of items in the response across all the pages 4. next(String) - This contains the hyperlink for the next page, if the current page is last, then the value will be null 5. previous(String) - This contains the hyperlink for the previous page, if the current page is the first page, then the value will be null 6. values(Array) - This is an array of dictionaries, where each dictionary corresponds to a user in SAFE and consists of the following values 1. peopleId(Integer) - The unique ID of the user. 2. emailId(String) - The email ID of the user. 3. firstName (String) - The first name of the user. 4. lastName(String) - The last name of the user. 5. uuid(String) - The unique identifier assigned to the user across SAFE. 6. updatedAt(String) - The timestamp when the user's details were last updated. 7. lastLoginTime(String) - The user's last SAFE login timestamp. 8. role(String) - The role of the user in SAFE. 9. authenticationType(String) - The authentication type of the user logging into SAFE. This value can be either Native (login via SAFE's MFA), or SSO (login via SSO). Media type application/json Controls Accept header. Example Value Schema { "size": 1, "page": 1, "pagelen": 10, "previous": null, "next": "https://example-domain.safeone.ai/api/v3/users?page=2&pagelen=100", "values": [ { "peopleId": 1, "emailId": "john.doe@domain.com", "firstName": "John", "lastName": "Doe", "uuid": "12345678-1234-1234-1234-123456789012", "updatedAt": "2022-01-13T05:03:50.428Z", "lastLoginTime": "2022-01-13T05:03:50.428Z", "role": "Admin", "authenticationType": "Native" } ] } | No links | | 401 | UNAUTHORIZED Media type application/json Example Value Schema { "status": "error", "message": "invalid authorization header!" } | No links | | 403 | FORBIDDEN Media type application/json Example Value Schema { "Message": "User is not authorized to access this resource with an explicit deny" } | No links | ## POST /api/v3/reports: This API helps SAFE users to trigger reports. We can use the same API to trigger Audit Logs export. It will return a UUID which needs to be used in the next API. Parameters | Name | Description | | --- | --- | | NA | NA | #### Example Request: The following example shows how SAFE users can call this POST API via cURL to request the audit logs for the past 1 day: | curl -X 'POST' \ 'https://us.safeone.ai/api/v3/reports' \ -H 'accept: application/json' \ -H 'Authorization: Bearer {{safe-bearer-token}}' \ -H 'Content-Type: application/json' \ -d '{ "type": "AUDIT_LOGS", "format": "csv", "reportMeta": { "days": 1 } }' | | --- | #### Responses | Code | Description | Links | | --- | --- | --- | | 202 | A UUID is provided by SAFE in the response. Media type application/json Example Value Schema { "success": true, "message": "Report generation request is queued and will be processed shortly", "data": { "uuid": "1eebc0b2-b019-42b3-8132-c15c5926b21e" } } | No Links | | 401 | UNAUTHORIZED Media type application/json Example Value Schema { "message": "Unauthorized" } | No Links | ## GET /api/v3/reports/: This API allows SAFE users to retrieve the Audit logs using UUID generated from the previous API i.e., POST /api/v3/reports. Parameters | Name | Description | | --- | --- | | NA | NA | #### Example Request: The following example shows how SAFE users can call this GET API via cURL to get the audit logs for the past 1 day by providing the UUID: | curl -X 'GET' \ 'https://preprod.safeone.ai/api/v3/reports/1eebc0b2-b019-42b3-8132-c15c5926b21e' \ --header 'Authorization: Bearer {{safe-bearer-token}}' | | --- | Note: Replace the UUID (highlighted in bold above) with your UUID generated from the previous API. #### Responses | Code | Description | Links | | --- | --- | --- | | 200 | Provides a pre-signed link. Clicking/opening the link in a browser lets the user download a CSV containing the audit logs. Media type application/json Example Value Schema { "success": true, "message": "Please download the report from the provided URL. The link will expire in 5 minutes.", "data": { "preSignedUrl": "" } } | No Links | | 400 | Bad Request Media type application/json Example Value Schema { "success": false, "message": "Report not found for report id:1eebc0b2-b019-42b3-8132-c15c5926b21e" } | No Links | > [!NOTE] > Notes > > If the customer does not want to have a live integration with dynamic updates which, they can build scripting to query our APIs periodically: > > POST /api/v3/audit-logs/export > > GET /api/v3/audit-logs/export/ > > The first API takes the number of days as a payload and returns a UUID which needs to be passed to the second one. A customer can use this on a daily basis to pull data and dump it to an S3 or similar for post-processing. > > These APIs are not intended for regular polling. Audit logs can be retrieved covering a minimum of a 24-hour period (e.g. time of request - 24 hours). SAFE monitors API usage and reserves the right to limit traffic for audit logs if there is excessive usage.