Facebook Login for Devices

Implement Facebook Login for Devices to allow people to log into your app or service with their Facebook account. This feature allows people to log into devices with limited input or display capabilities such as smart TVs, digital photo frames, or Internet of Things devices.

With device login, your device shows an alphanumeric code and tells people to enter it on a web page on their desktop PC or smartphone. People using your app or service can then grant permissions. After your application gets permissions, the device receives an access token which your app uses to make Graph API requests to identify the person and get information to personalize their experience with the device.

If you're building a TV app for Apple TV, or Android TV, or Fire TV, you should use Facebook SDK for tvOS or Facebook SDK for Android.

This guide describes the manual integration of Device Login without using the above SDKs.

• User experience
• Implement Login for Devices
• Troubleshooting

User Experience

These guidelines describe how to design a clear, safe, and consistent login experience across devices and services.

1. Call-to-Action

First consider where in your user experience you want to ask people to log in or connect with Facebook. For some devices this will be right away, and for others it might be later in the experience.

To ensure the most usable, consistent, and reliable user experience, design the button to look as much as possible like the official Facebook Login button.

From a visual design perspective, this means that you should

1. Label the button with “Log in with Facebook” or “Connect to Facebook”.
2. Use white and the official Facebook brand blue: #1877F2.
3. If your device supports a graphical display, you can also incorporate the official “f” logo. According to the Facebook brand guidelines, the logo should always be either white or Facebook blue (#1877F2).

Where relevant, describe the benefit of logging in. For example, “find out what your friends are watching” or "see photos from your Facebook Albums”.

2. Display the Code

When someone clicks the call-to-action, your device makes a call to Facebook's API which returns a code.

In your interface, tell people that they need to visit a website and enter the code with the following message, “Next, visit facebook.com/device (http://facebook.com/device) on your desktop or smartphone and enter this code”. Display the full code you received from Facebook's Device Login API. The code is between 6 and 12 characters long.

You can include a Close or Cancel button so people can cancel the device login flow. This should return them to the initial login screen.

When the code displays on screen, your device polls the Device Login API to see if someone authorized your application. After a few minutes, if they have not entered their code, the Device Login API returns a code_expired error. When your device receives this error you should cancel the login flow and the interface should display the call-to-action.

QR codes may also be generated with the user code embedded in the url. This is done by adding the user_code parameter to the url:

https://www.facebook.com/device?user_code=<USER_CODE>

3. Authorization

This is the flow people see when they go to facebook.com/device on their desktop or mobile browser. First they see a text field where they can enter their code:

After they enter their code and click Continue they can choose the permissions they want to grant:

So people know their login process is successful, they then see a confirmation message:

4. Confirm Successful Login

On your device's interface, you should also display a confirmation message. Ideally this includes the person's name and, if possible, their Facebook profile picture.

Display this confirmation on your device until the person clicks a Continue button. Someone may have to enter the code into a computer at another location, so they may need time to return to your device and see the confirmation before continuing.

After the person clicks Continue, your device can then show a great, personalized experience.

5. Log out or Disconnect

People should be able to log out from your device, and your device should not store their connection with Facebook. To do this, provide a Log out from Facebook or Disconnect from Facebook option in your device's menu.

When someone selects this option, your device should delete the stored access token from its memory. If you store the access token in a database or cloud storage, you should also remove it there. You do not need to make an API call to invalidate the access token.

After someone logs out, your device should display the initial call-to-action in Step 1.

Implement Login for Devices

Facebook Login for Devices is for devices that directly make HTTP calls over the internet. The following are the API calls and responses your device can make.

1. Enable Login for Devices

Load your app's dashboard and change Product > Facebook login > Settings > Login from Devices to 'Yes'.

2. Generate a Code

When the person clicks the Connect to Facebook or Log in with Facebook call-to-action, you device should make an HTTP POST to:

POST https://graph.facebook.com/v2.6/device/login
       access_token=<YOUR_APP_ID|CLIENT_TOKEN>
       scope=<COMMA_SEPARATED_PERMISSION_NAMES> // e.g. public_profile,user_likes
       redirect_uri=<VALID_OAUTH_REDIRECT_URL>

The scope parameter is optional and must contain a comma separated list of Login Permissions which are approved for use in Login Review.

The CLIENT_TOKEN is found in your App Settings -> Advanced, and should be combined with your app ID (separated with a pipe, |) to form the complete access_token.

The redirect_uri is an optional parameter. When you supply a URL, the person will be redirected to the URL after completing the login successfully. This allows you to log the person into your app's website for additional account management. This URL must be a valid OAuth redirect URL as configured in your App Settings -> Advanced. The response is in this form:

{
  "code": "92a2b2e351f2b0b3503b2de251132f47",
  "user_code": "A1NWZ9",
  "verification_uri": "https://www.facebook.com/device",
  "expires_in": 420,
  "interval": 5
}

This response means:

1. Display the string “A1NWZ9” on your device
2. Tell the person to go to “facebook.com/device” and enter this code
3. The code expires in 420 seconds. You should cancel the login flow after that time if you do not receive an access token
4. Your device should poll the Device Login API every 5 seconds to see if the authorization has been successful.

3. Display the Code

Your device should display the user_code and tell people to visit the verification_uri such as facebook.com/device on their PC or smartphone. See User Experience.

4. Poll for Authorization

Your device should poll the Device Login API to see if the person successfully authorized your app. You should do this at the interval in the response to your call in Step 1, which is every 5 seconds. Your device should poll to:

POST https://graph.facebook.com/v2.6/device/login_status
       access_token=<YOUR_APP_ID|CLIENT_TOKEN>
       code=<LONG_CODE_FROM_STEP_1> // e.g. "92a2b2e351f2b0b3503b2de251132f47"

The response to this API call depends on where someone is in the authorization flow. You will either receive the access token or an error object with a specific subcode to parse:

5. Confirm Successful Login

When you receive an access token the person successfully authorized your application. You should persist this access token on the device.

So people know the login process succeeded, your device should display their name and if available, a profile picture until they click Continue. To get the person's name and profile picture, your device should make a standard Graph API call:

GET https://graph.facebook.com/v2.3/me?
      fields=name,picture&
      access_token=<USER_ACCESS_TOKEN>

You get a response in the form:

{
  "name": "John Doe", 
  "picture": {
    "data": {
      "is_silhouette": false, 
      "url": "https://fbcdn.akamaihd.net/hmac...ile.jpg"
    }
  }, 
  "id": "2023462875238472"
}

Display the person's name and profile picture until they click Continue on your device.

6. Store Access Tokens

Your device should persist the access token to make other requests to the Graph API.

Device login access tokens may be valid for up to 60 days but may be invalided in a number of scenarios. For example when a person changes their Facebook password their access token is invalidated.

If the token is invalid, your device should delete the token from its memory. The person using your device needs to perform the device login flow again from Step 1 to retrieve a new, valid token.

Troubleshooting

Can I make device flow requests over HTTP?
OAuth 2 requires TLS/HTTPS.

Can I make device flow requests with the GET method?
All device flow requests should be POST requests.

How can I refresh my device login access token?
Device login access tokens may be valid for up to 60 days.

If the token is invalid, your device should delete the token from its memory. The person using your device needs to perform the device login flow again described here in Step 1 to retrieve a new, valid token.

To learn more about refreshing tokens, refer to Access Tokens.

I'm getting a Invalid API method error when making a POST request, what's wrong?
If you're making a POST request and getting an error like this:

{"error":{"message":"Invalid API method","type":"OAuthException","code":3}}

You may need to enable Login from Devices in your app.

Load your app's dashboard and set Product > Facebook login > Settings > Login from Devices to 'Yes'.

My device login access token is invalid. What do I do?
If your access token is invalid, your device should delete the token from its memory and obtain a new token. The person using your device needs to perform the device login flow again described here in Step 1 to retrieve a new, valid token.