Security Audit Logs API (Beta)

Overview

The Security Audit Logs API for Meta Admin Center allows admins of organization to access records of security-related events on Admin Center, across managed devices and managed Meta accounts.

With this API, your organization can connect Admin Center with other tools to record and monitor detailed insights about account activities, device activities and overall system changes, for the purpose of security monitoring, legal compliance and archival.

This API is currently in beta and subject to change before being made generally available.

Using the API

The Security Audit Logs API is available to organizations using Admin Center via custom integrations.

In order to use the API, you need to have the correct permissions to create and manage custom integrations for your organization on Admin Center.

Follow the steps below to use the API:

Within Admin Center, navigate to the People panel, then open the Identity providers tab.
Click the Connect button, then choose Custom setup to create a new integration for your organization. Add the name and description as required, and provide a list of IP addresses from which the API calls will be made.
On the Permissions tab for your custom integration, add the permission Read security audit logs.
Get an access token for your custom integration by following the steps in the Permissions and access tokens guide.
Make API requests to the security audit logs API endpoint with the required parameters.

Custom integrations are scoped to the Admin Center where they were created.

Endpoint

Use this endpoint when making API requests:

https://graph.work.meta.com/security_audit_logs

See usage examples for how to use this endpoint with access tokens in code.

Query parameters

Supported query parameters when calling the API:

Parameter	Description
`fields`	Specify the fields to be returned with data. See the response schema below for more details.
`before`	Pagination cursor for getting results after a specified cursor.
`after`	Pagination cursor for getting results before a specified cursor.
`limit`	Number of results to return in a single API request. Default: 50 Max limit: 1000
`startTime`	Filter to return events after start time. Format: ISO8601 Example: `2024-09-19T14:24:22+0000`
`endTime`	Filter to return events before end time. Format: ISO8601

Note: You can not send both after and before parameters in the same query.

Response schema

The API response will comprise a JSON object with a field called “data”, which contains an array of security event objects.

Each event object will contain the following fields:

Field name	Data type	Description
`event`	`string`	The type of event being logged (e.g. 'Login', 'New role assigned').
`actor_username`	`string`	The username of the actor of the event, e.g. an admin who assigned a new role to a user. Note: For events where the actor and the target are the same (e.g. 'Log in' / 'Log out'), only the target_username field is returned.
`target_username`	`string`	The username of the target of the event, e.g. the person whose account password was reset by admin.
`ip_address`	`string`	The IP address from where this event’s action was taken.
`timestamp`	`string`	The Unix timestamp of when this event occurred.
`useragent`	`string`	The Useragent of the device from where this event's action was taken.
`extra_data`	`Object`	Extra data which gives more information about the event. Shape: `summary`: Gives a summary about the event. Eg Name of wifi added on a device.

Available events

Below is a list of events that are currently available via the API. This list is subject to change as events are added or removed.

The events available are dependent on the Meta tools being used with Admin Center.

User logged in
Organization name changed
User performed SSO-login
Account disabled
User SSO-login failed
Invalid authentication event for 2FA
Account unlocked
Unusual account activity
Logged out
Password changed
Password reset succeeded
Password reset code requested
Password reset incorrect code
Compromised credentials found
Forced logout
Account deactivated
Account activated
Account deleted
Forced password reset
SSO reauthenticated
Account added
Two factor authentication method changed
Device released
User authentication method has been changed
Permission Role Created
Two factor authentication enforcement enabled
Two factor authentication enforcement disabled
Domain added
Domain verified
Domain removed
Product added
Product disconnected
Product scheduled for deletion
Product reconnected
Permission role updated
Permission Role Deleted
Permission Role Name Changed
Permission role added user
Permission Role Removed User
Suspicious login attempt
Email Domains On SSO Provider Changed
New identity provider added
Identity provider deleted
SAML URL for identity provider updated
Issuer URL for identity provider updated
Certificate for identity provider updated
Device wipe
Device provisioned
Person invited
Login failed
Identity provider activated
Identity provider deactivated
Email changed
People group deleted
People group created
People group updated
People group members changed manually
People group membership conditions changed
Email added
Employee information exported
Phone number added
Add New Admin from Existing User
Default device profile set
Device profile (third-party device manager) deleted
Network (Wi-Fi) added
Account recovered
Device profile (third-party device manager) updated
Network (Wi-Fi) updated
App added
Network (Wi-Fi) deleted
App updated
App deleted
Device group created
Device group updated
Device group deleted
Device moved to another group
SSO Single Logout URL changed
App assigned to device
Device removed from a group
Network (Wi-Fi) assigned to device
SSO Single Logout enabled
SSO Single Logout disabled
Device profile swapped
Untrusted device
Workrooms app login was enabled
Workrooms app login was disabled
DYI Download
Network (VPN) added
Network (VPN) updated
Network (VPN) deleted
Device security rule assigned to device is changed
Device security rule removed from device
Security rule assigned to device profile changed
Security rule removed from device profile
Device configured independently
Security rule added
Security rule updated
Security rule deleted
Device profile (Admin Center) created
Device profile (third-party device manager) created
Device profile (Admin Center) updated
Device profile (Admin Center) deleted
Network (VPN) assigned to device
Remove network (Wi-Fi) assigned to device
App ID and app secret viewed
Security Logs Exported
Account data download requested
Integration edited
Certificate added
Certificate deleted
Certificate updated
Integration access token reset
Unused permissions automatically removed
Integration created
Third party app install
Integration deleted
Third party app uninstall
Connected Device To Account
Certificate added to device
Certificate added to profile
Certificate removed from profile
Certificate removed from device
Meta Quest for Business upgrade
Domain Settings Updated
External relationship accepted
External relationship declined
Invited to external relationship
External access approval type changed
External relationship member approved
External relationship member rejected
Member re-added to external relationship
Member added to external relationship
Member removed from external relationship
Product added to external relationship
Product removed from external relationship
Remove network (VPN) assigned to device
Network (VPN) assigned to device profile
Remove network (VPN) assigned to device profile
Role added to external relationship
Account locked due to suspicious activity
Account unlocked
Role removed from external relationship
Suspicious login attempt blocked
Default device profile removed
External account disabled
Network (Wi-Fi) assigned to device profile
Remove network (Wi-Fi) assigned to device profile
Admin invited developer to access private apps
Q4B OS Config Update
Casting link edited
Organization logo changed
Policy triggered
Policy created
Policy updated
Policy deleted
Requested to manage subscriptions
Accepted Request To Manage
Declined Request To Manage
Policy deactivated
Policy activated
Admin Force Reauth All Users
Email Verification Code Validated
Bulk User Edit File Export
Password re-authenticated
Two Factor Authentication SMS Code Resend
Email Verification Code Requested
Trusted Relationship Share Code Generated
Log out from everywhere except current session
Send Verification Email For Delta
Verification Email Sent

Example

Request

GET /security_audit_logs/ HTTP/1.1
Host: graph.work.meta.com
Authorization: Bearer {your access token}
User-Agent: {your user agent}

Response

{
  "data": [
    {
      "timestamp": "2024-06-13T11:57:14+0000",
      "event": "PASSWORD_CHANGE",
      "ip_address": "0.0.0.0",
      "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36",
      "target_username": "username_target@example.com",
      "actor_username": "username_actor@example.com",
      "extra_data": {
        "summary": "Password changed"
      },
      "id": "123123123123123"
    },{
      ...
    }
],
  "paging": {
    "cursors": {
      "before": {before_cursor},
      "after": {after_cursor}
    },
    "next": "https://graph.work.meta.com/v1.0/security_audit_logs?access_token={your_access_token}&limit=50after={after_cursor}",
    "previous": "https://graph.work.meta.com/v1.0/security_audit_logs?access_token={your_access_token}&limit=50&before={before_cursor}"
  }
}