Permissions and access tokens

API Access for Meta Admin Center is controlled by permissions and access tokens.

Access Tokens are required when making API calls by an integration, and they represent both the integration and the permissions granted to it.

Permissions

Permissions enable granular control over what type of data can be accessed or edited by each integration. When developing an integration, admins can use permissions to control the level of available functionality for that integration.

Permissions granted to an integration take effect at the Admin Center instance level. For example, a custom integration with the Manage Accounts permission can manage or create user accounts only for the Admin Center where it was created.

The following permissions are available to custom integrations for Admin Center:

• Manage accounts, used by the account management API.
• Read security audit logs, used by the security audit logs API.

The permissions available for a custom integration are informed by its purpose. For example, an integration created within the Security tab of Admin Center can only use the Read security audit logs permission.

Access tokens

Access tokens are required when making API requests, and each access token is linked to the custom integration for which it was generated.

Configuring a custom integration

To configure a custom integration to make API calls, follow the steps below:

1. Navigate to the Identity providers tab on the People panel within Admin Center, and click the Connect button.
2. Choose Custom setup from the options presented, and fill in the details as required, including a name and description and a list of allowed IP addresses.
3. Retrieve the App ID and app secret for your integration, by clicking View in the App ID & App Secret section
4. In the App ID and App Secret tab for your integration, retrieve and safely store the App ID and App secret.
5. Securely store the app ID and app secret. These will be used in code to generate access tokens, as described below.

Generating an access token

Once you have configured a custom integration, you need to generate a token in order to make API calls. You'll do this by calling an access token endpoint, passing the App ID and App Secret you stored from the previous section, as shown in the example call below.

curl \
  -F 'access_token=<app_id>|<app_secret>' \
  -F 'grant_type=client_credentials' \
  https://graph.work.meta.com/work_get_token

This endpoint will return an access token that can then be used to make other API calls.

The access token returned by the above API call will expire, so you'll need to handle token expiry in your code, and retrieve fresh tokens periodically from the same endpoint you used to get the first token. See below for more information on token expiry.

Token expiry

Admin Center custom integration tokens are valid for exactly 2 hours after being generated.

After the validity period has passed, the token will expire, and can no-longer be used to make API calls.

To continue making API calls after an access token expires, a new token will need to be generated, and you'll need to replace the old token in any callsites that use it in code.

Reset a token

If you need to reset a valid access token for a custom integration, an admin can reset the app secret from the admin panel. Any access tokens in use by this custom integration will be immediately invalidated.

Security

Server IP allow list

To enhance the security of custom integrations, developers are required to add IP addresses of any services that will access the API for a given integration. This feature restricts token usage to servers at the specified IP addresses.

Security recommendations

Do

Do Not