# Audit Logs Account access logs for periodically auditing unauthorized access. When using Soracom in a multi-user organization, you may want to periodically check for indications of unauthorized access. **Audit Logs** provides detailed information about calls to the Soracom API performed against your Soracom account, including access to the User Console and Soracom CLI usage. When combined with [Soracom Access Management](https://docs.soracom.io/en/services/account/users-and-roles) (SAM), Audit Logs can be used to check the behavior of SAM users. > [!WARNING] > > Audit Logs record calls to the Soracom API made from your account. It is separate from the [Napter Audit Logs](https://docs.soracom.io/en/services/napter/audit-logs) feature, which records the connections made to your devices through the Napter on-demand remote access service. ## Log Details Audit Logs will record the following information: - The **timestamp** of API access - The **IP address** (IPv4/IPv6) used to call the API - The **username** corresponding to the authenticated user - If the authenticated user is the root account, `` will be recorded - If the authenticated user is a [SAM user](https://docs.soracom.io/en/services/account/users-and-roles), the username will be recorded - The **path** of the API request - The **status code** of the API request ## Subscriptions The following Audit Logs options are available: - **Standard Option** - This option is included by default for all Soracom accounts. The following features are provided in this option: - Logins to the User Console and calls made to the `/v1/auth` API are recorded. - Logs are retained for 24 hours. - Logs can be copied. - **Enterprise Option** - This optional subscription extends the functionality of the Standard Option with the following features: - Calls to all APIs are recorded. - Logs are retained for 366 days. - Logs can be filtered by API for easier searching. - Logs can be downloaded. ## Limitations - For security, individual logs cannot be deleted. - Similarly, for security, the recording of logs cannot be selectively disabled for certain users. - The following events are not recorded: - Access to Soracom Lagoon - Authentication failure events other than [Multi-Factor Authentication](https://docs.soracom.io/en/services/account/mfa) failures - Note that when MFA security is enabled for the root account or a SAM user, a `/v1/auth` log with status code `401` will be recorded as part of the MFA authentication process. This is normal behavior, and is not an indication of unauthorized access. - [API Sandbox](https://docs.soracom.io/en/developers/soracom-api/sandbox) activity - Information about the access method (User Console, API, or CLI) is not recorded. - If your root account password or any SAM user credentials are shared in your organization, Audit Logs cannot determine which individual is accessing your account. You may have to rely on the IP address information for further details. - As logs for APIs other than `/v1/auth` are not recorded in the Standard Option, when subscribing to the Enterprise Option, you will not be able to view such logs prior to when the subscription is enabled. Similarly, when unsubscribing from and subsequently re-subscribing to the Enterprise Option, you will not be able to view logs from the previous Enterprise Option subscription. - Logs are recorded asynchronously, and do not reflect access in real-time. ## Viewing Logs 1. Sign in to the **[User Console](https://console.soracom.io/?coverage_type=g)**. From the **☰ Menu**, expand **Logs & Statistics** and select **Audit Logs**. ![Audit Logs](https://docs.soracom.io/_astro/audit-logs.B2oXiHxH_Z2iGBWc.webp) If you are subscribed to the Enterprise Option, you can use the **API** menu to filter the logs. ## Downloading Logs If you are subscribed to the Enterprise Option, you can also download a copy of the logs for easier auditing. 1. Sign in to the **[User Console](https://console.soracom.io/?coverage_type=g)**. For security, in order to download Audit Logs, you must sign in using your root account email address and password. 2. From the **☰ Menu**, expand **Logs & Statistics** and select **Audit Logs**. 3. Click the **Download** button. 4. Select the time range of logs that you want to download. Then click **Get link**. ![Download Audit Logs](https://docs.soracom.io/_astro/download-audit-logs.GKekh5pU_Z2utiNY.webp) Depending on the amount of logs recorded within the specified time range, the log may take a few minutes to prepare. Once the log has been prepared, an email containing a download link will be sent to the account's primary email address. ## Changing Subscription > [!WARNING] > > Subscribing to the Audit Logs **Enterprise Option** will incur a monthly service fee until subscription is cancelled. Refer to the [Pricing & Fee Schedule](https://docs.soracom.io/en/pricing) for more information. 1. Sign in to the **[User Console](https://console.soracom.io/?coverage_type=g)**. For security, in order to change your Audit Logs subscription, you must sign in using your root account email address and password. 2. From the **☰ Menu**, open the **Audit Logs** screen. 3. A notification indicating your current Audit Logs option will be displayed above the list of logs. - To subscribe to the Enterprise Option, click the **Subscribe** link. - To unsubscribe from the Enterprise Option, click the **Unsubscribe** link. 4. After reviewing the details of the subscription change, click the **Subscribe** or **Unsubscribe** button to confirm the change. When changing subscriptions, the new option may take up to 20 minutes to take effect. ## Programmatic Usage You can also access Audit Logs using the Soracom API or CLI in order to integrate a periodic audit procedure as part of your operations. ### Soracom API To access the Soracom API, first use the [**auth**](https://docs.soracom.io/en/api#!/Auth/auth) API to obtain an API Key and Token. Refer to the [**API Usage Guide**](https://docs.soracom.io/en/developers/soracom-api) for instructions on how to use the API Key and Token in API requests. Then, use the [getApiAuditLogs](https://docs.soracom.io/en/api#!/AuditLog/getApiAuditLogs) API to retrieve logs: **Global** ```bash curl -X GET \ -H 'X-Soracom-API-Key: ' \ -H 'X-Soracom-Token: ' \ -H 'Accept: application/json' \ https://g.api.soracom.io/v1/audit_logs/api ``` **Japan** ```bash curl -X GET \ -H 'X-Soracom-API-Key: ' \ -H 'X-Soracom-Token: ' \ -H 'Accept: application/json' \ https://jp.api.soracom.io/v1/audit_logs/api ``` To limit the API to a specific time range, use the `from_epoch_ms` and `to_epoch_ms` query parameters in the request URL. You can also use the `limit` query parameter to limit the number of logs returned by the API. If Audit Logs contains more log entries than the specified limit, the API response will also return a `link` value in the response header indicating the request URL to use to retrieve the next set of logs. If you are subscribed to the Enterprise Option, you can also use the `api_kind` query parameter to filter the logs based on the API path. Ensure that the API path is URL encoded within the request URL. ### Soracom CLI To use the Soracom CLI, you must first configure it to authenticate with your account information, authorization key, or SAM user credentials. Then, run the following command to retrieve logs: **Global** ```bash soracom audit-logs api get --coverage-type g ``` **Japan** ```bash soracom audit-logs api get --coverage-type jp ``` Similar to the API, you can use the `--from-epoch-ms` and `--to-epoch-ms` flags to limit the response to a specific time range. You can also use the `--limit` flag to limit the number of logs returned by the CLI. Compared to the API usage, you can use the `--fetch-all` flag to automatically perform pagination and return all logs at once. If you are subscribed to the Enterprise Option, you can also use the `--api-kind` flag to filter the logs based on the API path.