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:

  1. Within Admin Center, navigate to the People panel, then open the Identity providers tab.
  2. 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.
  3. On the Permissions tab for your custom integration, add the permission Read security audit logs.
  4. Get an access token for your custom integration by following the steps in the Permissions and access tokens guide.
  5. 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

Query parameters

Supported query parameters when calling the API:

ParameterDescription

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.

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 nameData typeDescription

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}"
  }
}