Audit Logs
Audit Logs provide a searchable record of important actions in your Ashby organization. Use them to understand what changed, when it changed, and who or what performed the action. This article explains how to access Audit Logs in Ashby, review common events, and use the public API to store log data in your security or compliance systems.
Permissions and access
Audit Logs are available to organizations on the Enterprise plan. Only Organization Admins who receive explicit Audit Logs access can view the Audit Log in Ashby or create API Keys that can access the Audit Logs.
Foundations | Legacy Plus | Plus | Enterprise |
|---|---|---|---|
❌ | ❌ | ❌ | ✅ |
Elevated Access users do not have access to the Audit Log view. If they need to investigate an event, they can ask an Organization Admin with Audit Logs access to review it.
Audit Log entries are not filtered by user permissions. Organization Admins granted access to the Audit Log can see all events, even across candidates, applications and jobs they would normally be unable to access.
Prerequisites:
Ask your Customer Success Manager to grant Audit Logs access to at least one Organization Admin. After an Organization Admin receives access, they can grant access to other Organization Admins via the Permissions tab in their employee profile.
Audit Log overview
Audit Log entries record actions performed by people, API keys, automations, integrations, and Ashby Support. Depending on the event, an entry can include the time of the action, the actor, the target object, the event category, the channel the change came through, a human-readable description, and additional details.
The Audit Log can be viewed directly in the Ashby UI or can be retrieved over the API for ingestion into other systems.
The Audit Log Vocabulary lists the event categories currently supported by the Audit Log UI and API.
View the Global Audit Log directly in Ashby
After an Organization Admin receives access, follow the below steps to access and review the Audit Log.
- Navigate to Admin > Audit Logs.
- Select a date range. The Audit Log requires a date range before it displays results.
- Use the available filters to narrow the results to specific event categories, actors, or channels.
Some entries include additional metadata. Use the arrow on the left to expand an entry to view additional change information or more specific details for how the change was made.
Use the Audit Log API
Enterprise organizations can retrieve Audit Logs through the public API and send the results to an internal security information and event management (SIEM) system, data warehouse, or compliance tool.
To retrieve Audit Logs through the API:
- Create an API key with the auditLogsRead permission. Note that you can only enable this permission if you have access to audit logs in the Ashby web UI.
- Send requests to the auditLog.list endpoint.
- Use the Audit Log Vocabulary to select valid target types and event categories.
- Store and analyze the results in your internal system.
The API supports filters for dates, actors, target objects, target types, and event categories. It also supports pagination for retrieving larger result sets.
For API requests, use ISO 8601 dates in UTC. If you do not provide a date range, the API returns the previous 24 hours. An explicit date range can span up to 18 months.
Audit Log use cases
Audit Logs help Recruiting Operations, IT and Security, and Compliance and Legal teams investigate changes and monitor activity across their Ashby organization.
Investigate sensitive changes
Use Audit Logs to review changes that can affect your hiring workflows, candidate data, or organization security. Examples include:
- A job posting is published, unpublished, deleted, or edited.
- A candidate’s source changes, data is exported, or the candidate is anonymized or deleted.
- An offer is created, updated, extended, accepted, declined, cancelled, or approved.
- An API key is created, deactivated, or updated.
- A webhook or organization setting changes.
The available events depend on the target types and categories supported by Ashby. Review the Audit Log Vocabulary for the current list.
Audit access and permission changes
Use Audit Logs to understand how access changes over time. Examples include:
- A user account is activated or deactivated.
- A user’s global role, administrator permissions, or job and team access changes.
- An access role is created, updated, archived, restored, or deleted.
- A user logs in to or out of Ashby.
- An API key’s permissions change.
These events help you confirm whether a permission change occurred, identify the actor, and determine when the change happened.
Troubleshoot an unexpected change
When someone reports that a job, candidate, offer, or setting changed unexpectedly, use Audit Logs to narrow the investigation:
- Start with the approximate time when the change occurred.
- Filter by the actor if you know which person, API key, or automation may have performed the action.
- Review the event category and target object.
- Read the event description, changed fields, and available request details.
- If you need to investigate a specific target object or retrieve a larger set of results, use the auditLog.list API with the appropriate target filter.
Monitor security and compliance activity
Security teams can retrieve Audit Logs through the API and analyze them in their existing systems. This supports workflows such as:
- Monitoring changes to permissions, access roles, API keys, webhooks, and organization settings.
- Investigating potentially unauthorized or unexpected activity.
- Keeping an internal record of administrative changes for compliance reviews.
- Correlating Ashby events with activity from other business systems.
Data handling and limitations
- Audit Log entries are retained indefinitely.
- Certain Ashby User PII within an audit log entry (such as ip address) will be redacted after 30 days.
- We never directly store candidate personally identifiable information (PII) in our Audit Logs. An entry can store an internal candidate or application ID that API consumers can use to retrieve related information through another Ashby API endpoint. The in app Audit Log UI may resolve these IDs to user readable values by combining them with our primary operational database.
- Audit Logs cover the target types and event categories documented in the Audit Log Vocabulary. The initial release does not include every possible Ashby action, and we plan to expand event coverage over time.
- The current global Audit Log UI does not filter directly to a specific target object. Use the API when you need to query a known target ID.
- The initial global Audit Log view is limited to Organization Admins with explicit access. Object-specific history views for other users are not part of this initial release, but are planned for the future.
FAQs
How long are Audit Logs retained?
Audit Log entries are retained indefinitely. Certain user PII (such as IP Address data) will be redacted after 30 days.
Do Audit Logs contain candidate PII?
No. Audit Logs do not store candidate PII directly. Entries can include internal IDs that API consumers can use to look up related candidate or application information through another Ashby API endpoint.
Can I send Audit Logs to a security or data system?
Yes. Enterprise organizations can use the public auditLog.list API endpoint to retrieve and analyze Audit Logs in a SIEM, data warehouse, or other internal system. Create an API key with the auditLogsRead permission and use the Audit Log API reference for request details.
Why can’t I find a specific event?
Audit Logs cover a defined set of target types and event categories. Check the Audit Log Vocabulary to confirm whether Ashby currently records the event you are looking for.
Can I filter down to events that happen through the API or the MCP server?
Yes. The Audit Logs records the "channel" that an event came through. This tracks the broad interface that the actor used to make the change. You can filter the audit log to specific channels if you are interested, such as the MCP Server.
