Facebook Login

Session Info Access Tokens

If your app or website authenticates people with Facebook Login but manages users' logged-in state without an access token, you should create and use a session info token to monitor and log people out when the connection to their Facebook account is invalidated.

A session info access token is an access token tied to a Facebook Login session that does not grant access to user data. You can create a session info access token from a long-lived access token. A session info access token will become invalid when the session associated with the original access token expires or is invalidated.

Session Info access tokens can be used to improve security for your app by reducing access to data and tracking the status of a user's connection to your app.

Tracking Logged-In State

In the event of a security incident at Facebook, or when Facebook detects suspicious activity on an account, a person reports their account as hacked, or changes their password as a precaution, it is important that the accounts belonging to that person at the other services where they use Facebook Login are also protected. People can also choose to disconnect your app from their Facebook account from your app or website at any time, and such choices should also be reflected in the experience of your app. If you use Facebook's Android, iOS and JavaScript SDKs, access tokens are periodically checked in the background and your users will be automatically be logged out when these events happen.

If your app or website uses Facebook Login but keeps your users logged in with your own state management mechanisms, it is still important to monitor the Facebook Login sessions for your app and log people out in a timely fashion when they experience a security event or if they choose to disconnect your app from their Facebook account. If your app does not access user data from your server, you can retain and periodically verify a session info token instead of a full access token. This allows you to protect your users and their data in your app while also reducing any risk to Facebook user data should these tokens leak in a data breach or other security event at your servers.

Server-side proof of authentication

On Android and iOS, apps are required to use our SDK. Our SDK completes Facebook Login and gets a long-lived access token on the client device only. If your app needs to provision a user account server-side to enable login from other devices, it is important to have proof of the authentication event. Historically, this was done by passing the access token back to the server over a secure channel, and calling the debug_token endpoint to verify that it is valid and belongs to the app. If your app does not access user data server-side, we recommend using a session info token to provide the proof of authentication.

Tech Providers / Service Providers integrating Facebook Login on behalf of an app

Many apps use a service provider to integrate various federated authentication options (e.g. to offer Google, Apple, or Twitter products alongside Facebook Login) into their application behind a uniform API. If your app needs to share an access token with such a service provider as proof of authentication, to provision new users, or the provider wants to retain long-lived tokens for session monitoring and management, it is recommended that you give them a session info token for these purposes.

Exchanging Long-Lived Tokens for Session Info Tokens

If you need a session info access token you can generate one from a long-lived token. The workflow for generating a long-lived token is as follows:

Generate a Session Info Access Token

You will need the following:

  • A valid long-lived User or Page Access Token
  • Your App ID

Query the GET oauth/access_token endpoint.

curl -i -X GET "https://graph.facebook.com/{graph-api-version}/oauth/access_token?  
    grant_type=fb_attenuate_token           
    client_id={app-id}&
    fb_exchange_token={your-access-token}"

Sample Response

{
  "access_token":"{session-info-access-token}",
  "token_type": "bearer",
  "expires_in": 5183944            //The number of seconds until the token expires
}

Once you have retrieved the session info token, you can use it from your server or send it back to the client to use there.

Caveats

  • You can not use an expired token to request a session info token. If the token has expired, your app must send the user through the login flow again to generate a new access token.

  • You can not use a short-lived access token to request a session info token. Exchange your short-lived token for a long-lived token first if you are trying to obtain a debug-only token for your web application.

  • Generating a session info token does not require a client secret or app access token. Do not include your client secret or app access token in your app's source code. For Android and iOS apps, creation of the session info token should be done in your app before sending it to your server.

Using Session Info Tokens With the /debug_token Endpoint

To use the API, you can issue a Graph API request:

GET /debug_token?
  input_token={session-info-token}&
  access_token={your-access-token}
  • input_token: the session info token you want to get information about
  • app-access_token: an app access token or a valid user access token from a developer of the app

Please see the full documentation on Debugging and Error Handling for how to interpret return values and error messages from the API.

Caveats

  • Querying debug info for a session info access token still requires an app or developer access token. Session info tokens are intended for server-side use.

  • Session info tokens are valid only for the /debug_token GraphAPI endpoint, they cannot be used with the interactive access token debugger tool at this time.

  • Granular scopes are not returned for session info tokens to limit exposure of user data.