Access Tokens

An access token is an opaque string that identifies a user, app, or Page and can be used by the app to make graph API calls. When someone connects with an app using Facebook Login and approves the request for permissions, the app obtains an access token that provides temporary, secure access to Facebook APIs. Access tokens are obtained via a number of methods.

The token includes information about when the token will expire and which app generated the token. Because of privacy checks, the majority of API calls on Facebook need to include an access token. There are different types of access tokens to support different use cases:

This kind of access token is needed any time the app calls an API to read, modify or write a specific person's Facebook data on their behalf. User access tokens are generally obtained via a login dialog and require a person to permit your app to obtain one.

This kind of access token is needed to modify and read app settings. It can also be used to publish Open Graph actions. It is generated using a pre-agreed secret between the app and Facebook and is then used during calls that change app-wide settings. You obtain an app access token via a server-to-server call.

This kind of access token is similar to user access tokens, except that they provide permission to APIs that read, write or modify the data belonging to a Facebook Page. To obtain a page access token you need to start by obtaining a user access token and asking for the Page permission or permissions you need. Once you have the user access token you then get the page access token via the Graph API.

Client Token

The client token is an identifier that you can embed into native mobile binaries or desktop apps to identify your app. The client token isn't meant to be a secret identifier because it's embedded in apps. The client token is used to access app-level APIs, but only a very limited subset. The client token is found in your app's dashboard. Since the client token is used rarely, we won't talk about it in this document. Instead it's covered in any API documentation that uses the client token.

User Access Tokens

Although each platform generates access tokens through different APIs, all platforms follow the basic strategy to get a user token:

Short-Term Tokens and Long-Term Tokens

User access tokens come in two forms: short-lived tokens and long-lived tokens. Short-lived tokens usually have a lifetime of about an hour or two, while long-lived tokens usually have a lifetime of about 60 days. You should not depend on these lifetimes remaining the same - the lifetime may change without warning or expire early. See more under handling errors.

Access tokens generated via web login are short-lived tokens, but you can convert them to long-lived tokens by making a server-side API call along with your app secret.

Mobile apps that use Facebook's iOS and Android SDKs get long-lived tokens by default.

Apps with Standard access to Facebook's Marketing API when using long-lived tokens will receive long-lived tokens that don't have an expiry time. These tokens are still subject to invalidation for other reasons, but won't expire solely based on time. This is also true of access tokens for System Users in Business Manager.

Tokens are Portable

One important aspect to understand about access tokens is that they are portable. Once you have an access token you can use it to make calls from a mobile client, a web browser, or from your server to Facebook's servers. If a token is obtained on a client, you can ship that token down to your server and use it in server-to-server calls. If a token is obtained via a server call, you can also ship that token up to a client and then make the calls from the client.

Sample Code

Javascript

The Facebook SDK for Javascript obtains and persists user access tokens automatically in browser cookies. You can retrieve the user access token by making a call to FB.getAuthResponse which will include an accessToken property within the response.

Web (without JavaScript)

App Access Tokens

App access tokens are used to make requests to Facebook APIs on behalf of an app rather than a user. This can be used to modify the parameters of your app, create and manage test users, or read your apps's insights.

Limitations

Some user data that would normally be visible to an app making a request with a user access token isn't always visible with an app access token. If you're reading user data and using it in your app, you should use a user access token instead of an app access token.

App access tokens are considered insecure if your app is set to Native/Desktop in the Advanced settings of your App Dashboard and therefore will not work with API calls. This is because we assume that native or desktop apps will have the app secret embedded somewhere (and therefore the app access token generated using that secret is not secure).

Code Sample

This call will return an app access token which can be used in place of a user access token to make API calls as noted above. Again, for security, app access token should never be hard-coded into client-side code, doing so would give everyone who loaded your webpage or decompiled your app full access to your app secret, and therefore the ability to modify your app. This implies that most of the time, you will be using app access tokens only in server to server calls.

Note that because this request uses your app secret, it must never be made in client-side code or in an app binary that could be decompiled. It is important that your app secret is never shared with anyone. Therefore, this API call should only be made using server-side code.

There is another method to make calls to the Graph API that doesn't require using a generated app access token. You can just pass your app ID and app secret as the access_token parameter when you make a call:

The choice to use a generated access token or this method depends on where you hide your app secret.

Page Access Tokens

Page access tokens are used in Graph API calls to manage Facebook Pages. To generate a page access token, an admin of the page must grant your app the Page permission or permissions needed. Once granted, you can retrieve the Page access token using a user access token with the required permissions.

With a page access token you can make API calls on behalf of a Page. For example, you could post a status update to a Page (rather than on the user's timeline) or read Page Insights data.

Page access tokens are unique to each Page, admin, and app.

Access Token Length

Expect that the length of all access token types will change over time as Facebook makes changes to what is stored in them and how they are encoded. You can expect that they will grow and shrink over time. Please use a variable length data type without a specific maximum size to store access tokens.

Learn More

Use the Access Token Tool to see a list of your access tokens and debugging information for each token in.