The GitHub Enterprise Audit log API for GraphQL beginners
The newly shipped GitHut Audit log API allows you to make efficient queries for specific log data. Learn more about how to get started with the API.
![](https://github.blog/wp-content/uploads/2019/03/engineering-social.png?resize=1201%2C630)
Recently, GitHub announced an extension of the GitHub GraphQL API with our public beta release of the GitHub Audit log API for organizations using GitHub Enterprise. The initial release of the API exposes much of the same information you’d find in the “Audit log” section in the Settings tab of your organization.
Use the Audit log API to keep copies of your audit log data and monitor:
- Access to your organization or repository settings
- Changes in permissions
- Added or removed users in an organization, repository, or team
- Users promoted to administrators
- Organizations that have been added or removed
- Changes to permissions of a GitHub App
- Data for the current month and the last three months
You may have noticed this API is different than most of our other RESTful services. This is because the engineering team implemented a GraphQL interface with the intention of enabling you to make highly efficient queries for specific enterprise log entries. GraphQL can be tricky if you haven’t used it before, and while most of the concepts translate from REST, there are a few key differences. To help you get started with the Audit log API, we’re sharing a few useful steps, tips, and snippets of an actual query.
Create a query to get started
- Generate a personal access token (PAT) to authenticate your requests.
You can do this through the user developer settings under personal access tokens. - Grant full permissions to the PAT for both the repository and
admin:org
.
If SAML SSO isn’t enabled for your enterprise, revisit the PAT section and enable SSO access.
- If you haven’t already, download a GraphQL client. There are many useful tools available for free, like Postman’s latest version, Insomnia and GraphiQL.
- Now that you have your PAT and GraphQL client, it’s time to add the base URL.
The Audit log API base URL ishttps://api.github.com/graphql
. This URL remains the same regardless of which entities you query—this is part of the magic of GraphQL. When making a request, don’t forget to POST the query with your PAT as the Bearer Token.
- Set the following values in the “Headers” tab:
{“Content-Type”: “application/json”, “Accept”: “application/vnd.github.audit-log-preview+json”}
This “Accept” header is where we are programmatically opting in to the beta.
- Now we create the GraphQL query where we’ll request our enterprise organization for the latest five log entries.
{ organization(login: "<org-name>") { auditLog(last: 5, query: "actor:<user-name>") { edges { node { ... on AuditEntry { # Get Audit Log Entry by 'Action' action actorLogin createdAt # User 'Action' was performed on user{ name email } } } } } } }
The results
A JSON response that matches the same schema as your request is returned, each node in the collection of “edges” includes an action, the user that initiated that action, when the action took place, and which user it affected. Notice each of the five nodes only include the information we specifically requested with our query. Your enterprise can gain valuable insights from the information this query returned—but also more broadly from the Audit log API.
Now that you’ve made your first GraphQL request to the Audit log API, you can start learning how your enterprise works and make data-driven decisions about auditing on your team. If you have any questions or need more information check out our best practices or contact your account management team or the GitHub Sales Team.
Learn more about the Audit log API
Tags:
Written by
Related posts
![](https://github.blog/wp-content/uploads/2023/10/Collaboration-DarkMode-2.png?resize=400%2C212)
2024 is the biggest global election year in history. What’s at stake for developers?
GitHub is considering what is at stake for our users and platform, how we can take responsible action to support free and fair elections, and how developers contribute to resilient democratic processes.
![](https://github.blog/wp-content/uploads/2023/10/AI-DarkMode-2.png?resize=400%2C212)
GitHub named a Leader in the Gartner first-ever Magic Quadrant for AI Code Assistants
This year, as part of its annual Magic Quadrant series, Gartner published a first-of-its-kind report analyzing the state of play in the AI Code Assistants market–and named GitHub a Leader.
![AI in software development 2024 survey results with colorful graphics and percentages.](https://github.blog/wp-content/uploads/2024/08/ai-survey-header.png?resize=400%2C212)
Survey: The AI wave continues to grow on software development teams
We surveyed 2,000 people on software development teams at enterprises in the U.S., Brazil, India, and Germany about the use, experience, and expectations around generative AI tools in software development.