Page Access Tokens, Permissions, and Tasks

Before your app can make calls to read, update, or post to Pages, you need to get a Page access token. With this token you can view Page settings, make updates to page information, and manage a Page.

Permissions for Pages

When interacting with Pages via the Graph API, you need to ask for permissions using Facebook Login. Facebook Login allows your app to retrieve access tokens encoded with the permissions your app needs. Based on the feature you want to build, you need to ask for a different set of permissions. See the table below to learn about each permission's abilities.

Permission Abilities

manage_pages

Enables your app to retrieve Page Access Tokens for the Pages and Apps that the person administers.

publish_pages

Gives your app the ability to post, comment, and like as any of the Pages managed by a person using your app.

pages_messaging

Grants an app permission to manage and access Page conversations in Messenger.

pages_show_list

Enables your app to retrieve a list of Pages and Page Access Tokens that the person administers.

pages_manage_cta

Provides the access to manage call to actions of the Pages that you manage.

pages_manage_instant_articles

Enables your app to manage Instant Articles on behalf of a Facebook Page that the person administers.

Getting Page Access Tokens

Graph API requires Page access tokens to manage Facebook Pages. They are unique to each Page, admin, and app and have an expiration time. You must own or be able to perform a task on the Page to get a Page access token.

People using your app need to have one of the Page tasks described below.

For a Single Page

To get the Page access token for a single page, call the API endpoint /{page-id} using a user access token and asking for the field access_token. You need the permission pages_show_list or manage_pages to successfully execute this call.

GET /{page-id}?fields=access_token

The response will look like this:

{
  "access_token": "{your-page-access-token}",
  "id": "{page-id}"
}

For Multiple Pages

If a User grants your app the pages_show_list or manage_pages permission, you can use the /user/accounts or /me/accounts edge to get a list of all the Pages managed by that User, as well as a Page access tokens for each Page. The /me/accounts edge resolves to the /user/accounts edge when queried with a User access token.

GET /me/accounts

A list of Pages that the current User has access to will be returned. Access is defined by the Page tasks that the User has been approved for. The approved tasks for each Page will be listed in the tasks field:

Sample Response

{
  "data": [
    {
      "category": "Product/service",
      "name": "Sample Page",
      "access_token": "{page-access-token}",
      "id": "1234567890",
      "tasks": [
        "ADVERTISE",
        "ANALYZE",
        "CREATE_CONTENT",
        "MANAGE",
        "MODERATE"
      ]
    }
  ]
}

Note that versions older than 3.1 of the API returned Page roles and their permissions however Page roles have been deprecated and replaced by Page tasks as of October 26, 2018.

Permissions and App Review

For apps in live mode, all Page-related permissions except for pages_show_list require approval through the app review process.

Apps in development mode are allowed to use all Page-related permissions without app review. However, content published while an app is in development mode will be hidden from the public until the app is switched to Live mode.

Page-Scoped User IDs

When a User visits a Page, an ID is returned for that person for that specific page. The Pages API returns this Page-scoped ID, a PSID, for a User allowing your app to connect a customer's interactions with the Page across both Pages API and Messenger API. This will allow your app to connect public conversations that happen through Messenger for a given User and Page.

Before May 1, 2018, the Pages API returned App-scoped IDs, ASIDs. If your app used the Pages API and ASIDs before this date, you will need to migrate from your ASIDs to Page-scoped IDs within 180 days of your App Review approval at which time your ASIDs will no longer work. Only after you have completed the migration will your app receive PSIDs instead of ASIDs.

To facilitate the ASID to PSID migration process, use the Page-scoped ID API. This API allows you to map an ASID and a page to a PSID. You can then prepare your systems to be able to support PSIDs. Once your migration is complete we can then enable PSIDs to be returned via the Pages API endpoints.

The Page-scoped ID API will be available for 180 days from the date that your app passed App Review. The Pages API Migration section in your app's App Dashboard (Settings > Advanced > Pages API Migration) will display the number of days remaining for your app.

Page Tasks

Tasks allow Users to perform specific Page-related actions. When a User uses an app to interact with your Page, depending on the attempted action, we will first check if the User has been approved for a task that permits that type of action.

You can approve individual Users for the following tasks:

TaskPermitted Actions

ADVERTISE

Create ads and unpublished Page Posts

ANALYZE

View Insights

CREATE_CONTENT

Create Posts as the Page

MANAGE

Approve and manage Page tasks for Users

MODERATE

Respond to and delete comments, send messages as the Page

Changes

Beginning February 1, 2019, Page tasks have replaced Page roles. Under the old role-based model, assigning a role to a User granted that User permission to perform a set of actions. The new task-based model allows you to be more restrictive by only approving tasks that map to certain actions.

Use the table below to map roles to their equivalent actions:

RoleEquivalent Tasks

Admin

ADVERTISE, ANALYZE, CREATE_CONTENT, MANAGE, MODERATE

Advertiser

ADVERTISE, ANALYZE

Analyst

ANALYZE

Editor

ADVERTISE, ANALYZE, CREATE_CONTENT, MODERATE

Moderator

ADVERTISE, ANALYZE, MODERATE

Expiration

Page Access tokens expire. Your app can use a Page Access token for an hour after you originally get it.

If your app makes multiple requests to a node, the initial request gets a token and subsequent requests may get new tokens. The initial token will continue working as long as it has not expired.

If all of your app's Page tokens expire, you will need to request a new one.