What is the Access log API?
PinnedThe Access log API is a 90 day record of events that captures what an agent has accessed in your account (i.e. API calls that they've made), without necessarily updating, creating or deleting anything. We call these the “read” events and the Access log is your record of read events for your account.
In the API response you can see the full URL path of what was accessed, along with information about:
- Timestamp
- Query Params
- Http Method (Get/Post/…)
- User-ID of who made the request
- IP address of who made the request
This article explains how you authenticate against our APIs.
This is an example call to the Access log endpoint
https://[yoursubdomain].zendesk.com/api/v2/access_logs?filter[start]=2022-03-01T00:00:00Z&filter[end]=2022-03-12T00:00:00Z
filter[start] - should be older date
filter[end] - should be later date
Here’s an example of an JSON formatted response and its payload
{
"access_logs": [
{
"id: TYUHJKBHTYFGU",
"timestamp": "2022-03-11T00:10:34Z",
"user_id": 12345,
"ip_address": "00.00.000.85",
"url": "/api/services/access_logs",
"method": "GET"
},
{
"id:YTFCGVHBJKLJH",
"timestamp": "2022-03-11T00:13:38Z",
"user_id": 12345,
"ip_address": "00.00.000.85",
"url": "/api/services/access_logs",
"method": "GET"
},
{
"id:POIJUHGCTFYGUHJKHGF",
"timestamp": "2022-03-11T00:14:02Z",
"user_id": 12345,
"ip_address": "00.00.000.85",
"url": "/api/services/access_logs",
"method": "GET"
}
]
}
Supported filtering
By object
filter[start]- UTC Time stamp in format ofyyyy-mm-ddThh:mm:ssZfilter[end]- UTC Time stamp in format ofyyyy-mm-ddThh:mm:ssZfilter[path]- URL path. excluding query params.
Example
https://subdomain.zendesk.com/api/v2/access_logs?filter[start]=2022-08-01T15:04:05Z&filter[end]=2022-08-02T20:04:05Z&filter[path]=/api/v2/ticket_fields
By user
filter[start]- UTC Time stamp in format ofyyyy-mm-ddThh:mm:ssZ
filter[end]- UTC Time stamp in format ofyyyy-mm-ddThh:mm:ssZ
filter[user_id]- Number. Valid userID
Example
https://subdomain.zendesk.com/api/v2/access_logs?filter[start]=2022-08-01T15:04:05Z&filter[end]=2022-08-01T20:04:05Z&filter[user_id]=12345678
By timestamp
filter[start]- UTC Time stamp in format ofyyyy-mm-ddThh:mm:ssZ
filter[end]- UTC Time stamp in format ofyyyy-mm-ddThh:mm:ssZ
Example
https://subdomain.zendesk.com/api/v2/access_logs?filter[start]=2022-08-01T15:04:05Z&filter[end]=2022-08-01T20:04:05Z
Additional information about the API
- Requests are rate limited to 1000 requests per account per hour.
- Only agents with the Admin role will be able to get responses from the API.
- The API only captures data for the past 90 days.
- The API supports cursor-based pagination.
-
Official comment
Currently known limitations of the EAP
- A large part of our frontend uses a tool called GraphQL. For the purposes of this EAP it means that the URL path is obfuscated and we don’t know what was accessed as part of the request an agent made. You will see this /graphql path in some of the URLs.
- If your account moves pods at any point during this beta, you’ll lose access to the information and events that were created when you were on the old pod will not be copied over.
- There are still some parts of the product that we can’t gather information from; Explore, Sell etc.
-
Added a new bullet point to the Additional information section that calls out that the API supports cursor-based pagination.
-
Would this also show us when Zendesk employees access our data via account assumption or otherwise?
-
Hi Dan, apologies for the delayed response. I've not tested this myself but I assume that as a Zendesk employee accesses the account as another user, any action they take is logged as being taken by the user they accessed as. This is true for how events are captured in the Audit log today, and should also be true for the Access log.
-
Hi Caroline,
I have a question about /graphql results.
I see that there is a "graphql" property when that is the end point that is being accessed. This shows the query, name, type, and variable. which is great. However, is there a way to see the result of the query? For further context, we plan to pipe the logs into a longterm storage with the ability to query and filter later if needed so we have access longer than the 90 days of Zendesk. We are wanting to have a record of when an agent access customer data. getting just a query, while it does provide base and entry level information we are not able to view exactly what information they were able to see at the time of the event. For example, when an agent accesses a ticket the graphql give the variable of the ticket Id, but i do not know what customer if any is the requester to that ticket. If the behavior is slightly different when they go to a customer profile vs a ticket that would be a great thing to have documentation around we we can get a better idea of exactly is being accessed without needing to blindly open tickets based on the id alone. If we are able to see the results directly within the access log itself, or at the very least the ID of each object that is returned from the query
example: we query tickets with an ID: 12345, the assigneeID is 14567, the requester id is 4567889 and the follower ids are [123,456,789], etc
That will give us dramatically more actionable information increasing the usability of the api dramatically.I would be happy to jump on a call sometime to better explain our use case and desired outcomes.
-
Hi Chester, thanks so much for this detailed feedback. Let me pass it on to the team first for a quick check but I'll definitely take you up on the offer to chat as well.
-
As a initial reaction we're hesitant to add this information for two reasons: a) the query result could be massive and we've not investigated the feasibility of adding this type of load, and b) this would add PII to our internal logs that we've also not investigated the impact of.
I'll keep the discussion going with the team but there's a bunch of investigation and due diligence that would be needed for us to understand if this is feasible.
-
Hi, We seems to have some cases that logs cannot be found while the target APIs would be called internally. For example, when I opened an end user or an organization from agent workspace, I assume that an API (e.g. /api/v2/users/<id> or /api/v2/organizations/<id>) should be called, but nothing can be found in access log. Regarding to tickets and help center articles, we can find which data has been accessed by analyzing GraphQL log.
Is this a current limitation of functionality, or do I miss something? -
HI Shigeichi, apologies for the delayed response! We currently have a dependency on one of our internal services to supply accountID and userID headers; this is why the information isn't showing up for you. Current timeline for getting this resolved is end of August so I'll be back with an update for you then.
-
Updated the documentation to outline the supported filters; by user, by object and by timestamp.
-
Hi Caroline Kello! Thanks for the information so far.
The intro paragraph says, "...captures what an agent has accessed in your account". Are there any plans to capture what *users* are doing?
Do *light agents* count as *agent* activity that gets captured?
-
Hi Rusty,
We've currently no plans on extending this to capture end-user access events. What are some of the activity you'd like to see there? And what would you use that information for?
We didn't have Light Agent included in our original requirements, but we also didn't put any specific restrictions in place that would exclude them. I'll need to test this to confirm if it's captured - I'll be back once I have more information and I can update our EAP documentation at that point.
-
Hi Caroline Kello - thanks for the prompt and courteous reply. I was thinking really "edge case" stuff - like a user getting accidental escalated privileges and information that would be helpful in a security audit of such an event. Clearly not an "everyday" need and hopefully a never need. :)
I have a couple additional questions I'd love your insight on when time permits:1. Are "Light Agent" activities available as well as the "full" agent activity?
2. Is the data available via this API the same as what's found in the audit log in the admin interface? If not, in what way is it different? -
Ah, so if an end-user were to have their role set to that of a agent? That's something we already have events for in the Audit log.
1. If this is for the question if Light Agent activity is captured in the Access log, I'll get back to you on this.
2. There main answers you'll be able to get from the Access log is who viewed a ticket, who viewed a user profile, and what searches did an agent make (including the search term). This is not information that's currently available in the Audit log. I look at the Audit log as your record of Create, Update, Delete, Sign in events - and the Access log is your record of Read events.
-
This is a great step in the right direction allowing admins to access more information around what users are doing on the account. Great work Caroline Kello and team!
2 things from here:
1. I am throwing in my hat for +1 to light agent activity being captured inside the access log. It would be great is the activity could capture when a light agent initiates a new side conversation as well. That's quite important as I have quite a few clients where their light agents utilise side conversations. :)
2. The limitation around pod moves during EAP... once this feature goes GA, if a customer's account moves pods, will this limitation still be in play? Or is it an EAP only limitation?
-
Thanks, Amie! Some answers:
1. Forgot to follow up on Light Agents but confirmed that their activity is included. The only activity that's specifically excluded is end users.
2. We'll have support for Account Moves after GA, it's just an EAP limitation.
-
Thanks for the updates, Caroline. Glad to hear light agent activity is included and the Account moves limitation is just an EAP limitation. :)
-
Caroline Kello
Is the audit log only available via API, or are we able to see it in the current Audit log. Also is there a way to see when agents are logging in and out of Zendesk? -
Hey Denise,
Access log is API only right now. Would you prefer having some kind of UI for Access log? Agent sign in events is in the Audit log, but not sign out events.
-
Caroline,
Yes, having a UI for the Access Log would be great and much more useful for our managers, so they can view anytime, without having to ask me to run an API pull. . It would also be good to have when agents sign out as well.
-
I am +1 for all of this to be available in the admin centre UI as well.
There are many many ZD admins out there who don’t have API skills and having this info readily available to them inside the UI would be a huge advantage for holistic account management.
It’s great that the APi displays agent sign in events but it’s also equally important for us to be able to see agent sign out events too. This can help uncover whether agents are actually logging in and out of the zd each day for security reasons or not sticking to their roster etc.
Even just basic agent management both the sign in and sign out data is very useful :)
Please sign in to leave a comment.
21 Comments