Page Access Tokens, Permissions, and Roles

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

read_page_mailboxes

Provides the ability to read from the Page Inboxes of the Pages managed by a person

pages_show_list

Provides the access to show the list of the Pages that you manage

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 have a role on the Page to get a Page access token.

People using your app need to have one of the Page roles 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/acounts 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 Graph API v3.1+ Response

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

Note that older version of the API will return Page roles and their permissions instead. Page roles are undergoing deprecation and will be replaced by Page tasks for older versions of the Graph API on October 26, 2018.

Sample Graph API v<3.1 Response

{
  "data": [
    {
      "category": "Product/service",
      "name": "Sample Page",
      "access_token": "{page-access-token}",
      "id": "1234567890",
      "perms": [
        "ADMINISTER",
        "EDIT_PROFILE",
        "CREATE_CONTENT",
        "MODERATE_CONTENT",
        "CREATE_ADS",
        "BASIC_ADMIN"
      ]
    }
  ]
}

Permissions and App Review

Your app needs manage_pages and publish_pages permissions from the person who wants to post or message as a page. If your app request these permissions, then your app needs to go through Login Review.

Your app might not need to request these permissions because people posting are already set up with a role in your app's dashboard. If this is the case, you do not need to submit your app for review. See the Roles tab in App Dashboard.

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

Limitation

Page tasks are in the process of replacing Page roles. Under the old role-based model, you can assign a role to a User, which in turn grants that User permission to perform a set of actions. Under the new task-based model, you can be more restrictive by only approving tasks that map to certain actions.

However, Page tasks have not completely replaced Page roles yet. For this reason, when approving a User for certain tasks, you must approve them for all of the equivalent tasks associated with a given role. For example, to approve the User for the equivalent of an Advertiser role, you must approve them for the ADVERTISE and ANALYZE tasks.

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

Once Page tasks completely replace Page roles, this limitation will be removed and you can approve Users for any task combination that you like.

Page Roles

Page roles are undergoing deprecation. They have been replaced with Page tasks in Graph API v3.1, and will be replaced with Page tasks in all versions on October 24, 2018.

Facebook Pages have six different roles to access settings, publish content as a page, or perform operations with the Pages API. Depending on your Page role you may be able to execute a particular set of actions like posting as page or getting insights data.

When making API calls to the endpoint /{user-id}/accounts the current user's roles are listed in the key perms.

Role Description Roles this Applies To in the UI

ADMINISTER

Manage admins

Admin

EDIT_PROFILE

Edit the Page and add apps

Admin, Editor

CREATE_CONTENT

Create posts as the Page

Admin, Editor

MODERATE_CONTENT

Respond to and delete comments, send messages as the Page

Admin, Editor, Moderator

CREATE_ADS

Create ads and unpublished page posts

Admin, Editor, Moderator, Advertiser

BASIC_ADMIN

View Insights

Admin, Editor, Moderator, Advertiser, Analyst

For information on all Page roles and capabilities, see Facebook Help Center, Page Roles.

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.