Login API

Facebook Login for Apps is a fast and convenient way for people to create accounts and log into your app across multiple platforms. It’s available on iOS, Android, Web, Windows Phone, desktop apps and devices such as Smart TVs and Internet of Things objects.

Use Cases

Facebook Login is used to enable the following experiences:

• Account Creation – Facebook Login lets people quickly and easily create an account in your app without having to set (and likely later forget) a password. This simple and convenient experience leads to higher conversion. Once someone has created an account on one platform, they can log into your app—often with a single click—on all your other platforms. A validated email address means you’re able to reach that person to re-engage them at a later date.
• Personalization – Personalized experiences are more engaging and lead to higher retention. Facebook Login lets you access information which would be complex or arduous to collect via your own registration form. Even just importing someone’s profile picture imported from Facebook gives them a stronger sense of connection with your app.
• Social – Many highly retentive apps let people connect with their friends in order to enable shared in-app experiences. Facebook Login lets you know which of your app’s users are also friends on Facebook so you can build value by connecting people together.

Features

• Real Identity – When people choose to log in with Facebook, they can share their real identity through their public profile. Public Profile includes a person’s real name and a profile picture. Apps based on real identity often have less spam and foster higher quality conversations.
• Cross Platform Login – Facebook Login is available on the most common mobile and desktop app platforms. People who create accounts with Facebook on one platform can quickly and easily log into your app on another. A person is known by the same User ID everywhere so they can pick up your in-app experience where they left off. Facebook Login is available on iOS, Android, Web, and Windows Phone, for desktop apps and for devices such as Smart TVs and Internet of Things objects
• Works Alongside Your Existing Account System – Facebook Login complements your existing account system. Give people the option to log in with Facebook alongside email, SMS or other social login choices. Where an email address you get from Facebook Login matches one already in your system, you can log that person into their existing account without additional passwords.
• Granular Permissions – Facebook Login supports many permissions which determine which information people choose to share with your app. This means you have precise control over what you request and people have precise control over what they choose to approve.
• People Have Control Over What They Share – Great experiences start by giving people control. With Facebook Login, people can choose which information they share with your app. They can still get the benefits of logging in with Facebook even if they feel uncomfortable granting access to certain information. Your app can later re-request this information once you’ve explained how the person’s experience will be enhanced.
• Gradual Authorization – Facebook Login supports the gradual authorization—you don’t have to request all the information you want up front—you can do it over time. This means people can quickly and easily create accounts in your app—and as their experience with your app deepens, you can request addition information to further enhance their experience.
• Facebook Lite Integration for Android Apps – When you develop your app with version 4.14.0 of the Facebook SDK for Android, Facebook Login has automatic integration with Facebook Lite. If people don’t have the Facebook Android app installed, Facebook Login uses Facebook Lite instead to display the login screen and get credentials. Previous SDKs required that people have the Facebook app installed.

Permissions

When a person logs into your app via Facebook Login you can access a subset of that person’s data stored on Facebook. Permissions are how you ask someone if you can access that data. A person’s privacy settings combined with what you ask for will determine what you can access.

Facebook Login Example – Permissions are strings that are passed along with a login request or an API call. Here are two examples of permissions:

• email – Access to a person’s primary email address.
• user_likes – Access to the list of things a person likes.

For example, if you add the login button to a web app and ask for email and user_likes via the scope parameter, a person would be prompted with this dialog when logging in for the first time:

Your app has requested a person’s email address and the things they like but that request also automatically asks for access to a person’s public profile.

When to ask for Permissions – Your app can ask for additional permissions at any time, even after a person logs in for the first time. For example, the publish_actions permission lets you post to a person’s Facebook Timeline. It’s recommended you ask for this permission only when a person is ready to publish a story to Facebook. When you ask for new permissions, the person using your app will be asked about those new permissions and has the ability to opt out.

Permissions only need to be granted once per app, i.e. permissions granted on one platform are effectively granted on all the platforms your app supports.

User Control – Facebook Login allows a person to grant only a subset of permissions that you ask for to your app, except for public profile, which is always required. This is available as a separate screen in the login dialog when you ask for permissions:

Your app should handle the case where someone had declined to grant your app one of the permissions you requested.

Revoked Permissions – People can also revoke permissions granted to your app in Facebook’s interface at any time after they have logged in. It is important that your app regularly checks which permissions have been granted, especially when launching on a new platform.

Granular Permissions – People can grant your app permissions for Pages, Groups, and business assets they manage at the individual level. For example, someone who manages several Pages, may grant your app permission for only a particular page or for only some of the Page.

People choose which permissions they grant through a permission request flow. For example, if an app requests Page and Groups permission, people receive a request to grant those permissions.

If they don’t grant all the requested permissions, they can manage what sorts of permissions they grant.

They can also choose which Pages, Groups, or business assets they grant permissions for.

If someone initially grants only some of the requested permissions, they can later change which permissions they allow through the app settings page. However, if they update this to grant all permissions, they will no longer be able use the app settings page to change the permissions they have granted.

People can manage the following permissions at the individual level:

• manage_pages
• pages_manage_cta
• pages_manage_instant_articles
• pages_show_list
• pages_messaging
• pages_messaging_phone_number
• pages_messaging_subscriptions
• pages_messaging_payments
• publish_pages
• read_page_mailboxes
• business_management
• user_managed_groups

Read and Write Permissions

Each permission has its own set of requirements and suggested use cases. All these permissions, except the default fields, require that you have Client OAuth Login enabled for your app on the Facebook Login tab of your app dashboard.

The default fields and the email permission do not require Login Review, but all other permissions do. Access to the Public Feed API is restricted to a limited set of media publishers and usage requires prior approval by Facebook.

Read Permissions – User Attributes

• email
• user_age_range
• user_birthday
• user_friends
• user_gender
• user_hometown
• user_link
• user_location

Read Permissions – User Activity

• user_likes
• user_photos
• user_posts
• user_tagged_places
• user_videos

Read Permissions – User Events and Groups

• groups_access_member_info
• user_events
• user_managed_groups

Write Permission – User Events and Groups

• publish_to_groups

Default Fields – The default fields are a subset of the parts of a person’s public profile. These fields are the following properties on the User object:

• id
• first_name
• last_name
• middle_name
• name
• name_format
• picture
• short_name

On the web, the default fields are implied with every request and you don’t need to declare them, although the best practice is to declare them with public_profile. On iOS and Android, you must manually request these fields with public_profile, as part of your login flow. The id field is an app-scoped ID.

Access Tokens

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.

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. Access tokens are obtained via a number of methods, each of which are covered later in this document. 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:

Access Token Type	Description
User Access Token	The user token is the most commonly used type of token. 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.
App Access Token	This kind of access token is needed to modify and read the 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.
Page Access Token	These access tokens are 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 manage_pages permission. 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.

Refreshing User Access Tokens – User access tokens are either short-lived or long-lived. However, all access tokens must be renewed every 90 days with the consent of the person using your app. This means that every 90 days you must send a person through the login process and they must agree to the login by clicking the Continue button.

When you use iOS, Android, or our JavaScript SDK, the SDK will handle making sure that tokens are refreshed before they expire during this 90-day period. Native mobile apps using Facebook’s SDKs get long-lived access tokens, good for about 60 days. These tokens will be refreshed once per day, for up to 90 days, when the person using your app makes a request to Facebook’s servers. If no requests are made, the token will expire after about 60 days and the person will have to go through the login flow again to get a new token.

Access tokens on the web often have a lifetime of about two hours, but will automatically be refreshed when required. If you want to use access tokens for longer-lived web apps, especially server side, you need to generate a long-lived token. A long-lived token generally lasts about 60 days. This is what the process for generating a long-lived token looks like:

To generate a long-lived token:

• Start with a short-lived token generated on a client and ship it back to your server.
• Use the user token, your app ID and app secret to make the following call from your server to Facebook’s servers:

GET /oauth/access_token?

grant_type=fb_exchange_token&

client_id={app-id}&

client_secret={app-secret}&

fb_exchange_token={short-lived-token}

Make this call from your server, not a client. The app secret is included in this API call, so you should never actually make the request client-side. Instead implement server-side code that makes the request, then pass the response containing the long-lived token back to your client-side code. This will be a different string than the original token, so if you’re storing these tokens, replace the old one.

Once you’ve retrieved the long-lived token, you can use it from your server or ship it back down to the client to use there.

An important note: Apps are unable to exchange an expired short-lived token for a long-lived token. The flow above only works with short-lived tokens that are still valid. Once they expire, your app must send the user through the login flow again to generate a new short-lived token.

Extending Page Access Tokens – Apps can retrieve a page access token from Page admin users when they authenticate with the manage_pages permission. If the user access token used to retrieve this page access token is short-lived, the page access token will also be short-lived.

To get a longer-lived page access token, exchange the User access token for a long-lived one and then request the Page access token. The resulting page access token will not have any expiry time.

Login Security

The features of Facebook Login such as access tokens and permissions make it safe and secure for people and apps to use, but there are some security steps that apps need to implement themselves.

• Security Checklist
• The App Secret
• Secure Server-side Calls with appsecret_proof
• Secure Client-side Calls with Short-term Tokens and Code Flow
• Token Hijacking
• State Parameter
• Enable Strict Mode
• Lock Down Your Facebook App Settings

Security Checklist – This list below should be considered the absolute minimum that all apps using Facebook Login should implement. Other features will be unique to your app and you will need to always think about how to make your app as secure as possible. Apps that are not secure will lose the trust of their audience and people will stop using them.

• Never include your App Secret in client-side or decompilable code.
• Sign all server-to-server Graph API calls with your App Secret.
• Use unique short-term tokens on clients.
• Don’t trust that access tokens in use by your app were actually generated by your app.
• Use the state parameter when using the login dialog.
• Use our official SDKs where possible.
• Reduce your app’s attack surface area by locking down your Facebook app settings.
• Use HTTPS.

The App Secret – The App Secret is used in some of the Login flows to generate access tokens and the Secret itself is intended to secure usage of your App to only those that are trusted. The secret can be used to easily create an App Access Token which can make API requests on behalf of any user of the app, which makes it extremely important that an App Secret is not compromised.

Therefore the App Secret or an App Access token should never be included in any code that could be accessed by anyone other than a developer of the app. This applies to all methods of code that are not secured like client-side code (such as HTML or Javascript) or native apps (such as iOS, Android or Windows desktop apps) that could be decompiled.

We recommend that App Access Tokens should only be used directly from your app’s servers in order to provide the best security. For native apps, we suggest that the app communicates with your own server and the server then makes the API requests to Facebook using the App Access Token. For this reason, if your ‘App Type’ under Advanced Settings in the App Dashboard is set to Native/Desktop we assume that your native app contains the App Secret or an App Access Token in the binary, and we do not allow calls signed with an App Access Token to proceed. The API will behave as though no access token was provided.

If your App Secret is compromised, you should reset it immediately in the Basic Settings of your App Dashboard. When you start the reset process, you can specify a number of hours that the compromised secret will continue to work for when making requests, however anything sent from Facebook (such as signed requests) will use the new secret straight away, so you must adjust your code to expect it as soon as possible.

Secure Server-side Calls with appsecret_proof – You can reduce your exposure to malware and spammers by requiring server-to-server calls to Facebook’s API be signed with the appsecret_proof parameter.

Secure Client-side Calls with Short-term Tokens and Code Flow – In some configurations, apps will reuse a long-term token across multiple clients. Don’t do this. Instead use short-term tokens that are generated with the code flow.

Token Hijacking – To understand how this happens, imagine a native iOS app that wants to make API calls, but instead of doing it directly, communicates with a server owned by the same app and passes that server a token generated using the iOS SDK. The server would then use the token to make API calls.

The endpoint that the server uses to receive the token could be compromised and others could pass access tokens for completely different apps to it. This would be obviously insecure, but there is a way to protect against this – access tokens should never be assumed to be from the app that is using them, instead they should be checked using debugging endpoints.

State Parameter – If you’re using the Facebook login dialog on your website, the state parameter is a unique string that guards your application against Cross-site Request Forgery attacks.

Enable Strict Mode – Strict Mode keeps apps safe by preventing bad actors from hijacking your redirect. Enabling Strict Mode is required for all apps.

Before turning on Strict Mode in the App Dashboard, ensure your current redirect traffic still works by taking the following actions in Facebook Login settings:

• For apps with dynamic redirect URIs, use the state parameter to pass back the dynamic information to a limited number of redirect URIs. Then add each of the limited redirect URIs to the Valid OAuth redirect URIs list.
• For apps with a limited number of redirect URIs, add each one to the Valid OAuth redirect URIs list.
• For apps using only the Facebook JavaScript SDK, redirect traffic is already protected. No further action is needed.

After taking these actions, make sure to enable strict mode.

How Strict Mode Works – Strict Mode prevents hijacking of your redirect URIs by requiring an exact match from your Valid OAuth redirect URIs list. For example, if your list contains www.example.com, then Strict Mode won’t allow www.example.com/token as a valid redirect. It also won’t allow any extra query parameters not present in your Valid OAuth redirect URIs list.

Lock Down Your Facebook App Settings – Enable and/or disable any authentication flows that the app does not use to minimize attack surface area.

• Use code-generated short-term access tokens in clients instead of client-generated tokens or server-provided long-term tokens. The code-generated short-term access tokens flow requires the app server to exchange the code for a token, which is more secure than obtaining a token in the browser. Apps should prefer using the this flow whenever possible to be more secure – if an app only enables this flow, malware running on a user’s computer cannot obtain an access token to abuse.
• Disable Client OAuth Login if your app does not use it. Client OAuth Login is the global on-off switch for using OAuth client token flows. If your app does not use any client OAuth flows, which include Facebook login SDKs, you should disable this flow. Note, though, that you can’t request permissions for an access token if you have Client OAuth Login disabled. This setting is found in the Products > Facebook Login > Settings section of the App Dashboard.
• Disable Web OAuth Flow or Specify a Redirect Whitelist. Web OAuth Login settings enables any OAuth client token flows that use the Facebook web login dialog to return tokens to your own website. This setting is in the Products > Facebook Login > Settings section of the App Dashboard. Disable this setting if you are not building a custom web login flow or using the Facebook Login SDK on the web.
• Enforce HTTPS. This setting requires HTTPS for OAuth Redirects and pages getting access tokens with the JavaScript SDK. All new apps created as of March 2018 have this setting on by default and you should plan to migrate any existing apps to use only HTTPS URLs by March 2019. Most major cloud application hosts provide free and automatic configuration of TLS certificates for your applications. If you self-host your app or your hosting service doesn’t offer HTTPS by default, you can obtain a free certificate for your domain(s) from Let’s Encrypt.
• Disable embedded browser OAuth flow if your app does not use it. Some desktop and mobile native apps authenticate users by doing the OAuth client flow inside an embedded webview. If your app does not do this, then disable the setting in Products > Facebook Login > Settings section of the App Dashboard.
• Disable mobile single sign on flows if your app does not use them. If your app does not use iOS or Android Login, disable the ‘Single Sign On’ setting in the iOS and Android sections of Settings > Basic .

The App Dashboard contains a number of additional settings which allow developers to shut down areas of attack that might otherwise lead to security issues:

• Basic > App Secret if your app secret is ever compromised, you can reset it here.
• Basic > App Domains use this to lock down the domains and subdomains which can be used to perform Facebook Login on behalf of your app.
• Advanced > App Type when you create a native app for mobile or desktop and include the app secret within, set this to Native/Desktop to protect against your app being decompiled and your app secret stolen.
• Advanced > Server IP Whitelist specifies a list of IP addresses from which Graph API calls can be made with your app secret. Graph API calls made with your app secret from outside of this range will fail. Calls made with user access tokens are not affected by this setting.
• Advanced > Update Settings IP Whitelist locks down the IP addresses from which someone can modify these app settings to a specific range. Take care setting an IP Whitelist on residential broadband. If your IP address changes you will lose the ability to edit your app’s settings.
• Advanced > Update Notification Email notifies an email address whenever any app setting is changed in the App Dashboard.
• Advanced > Stream post URL security this will stop your app from publishing any URLs that don’t point back to a domain it owns. This will not always be useful, specifically if you know your app will publish links to other sites.

Use HTTPS – Use HTTPS, instead of HTTP, for redirects, the JavaScript SDK, and as an internet protocol, because it uses encryption. HTTPS keeps transmitted data private and guards against eavesdropping attacks. It also prevents data from being tampered with during transmission by, for example, introducing advertisements or malicious code.

An Enforce HTTPS setting for Facebook Login is available in your App Dashboard. When you turn it on, it requires all Facebook Login redirects to use HTTPS, and that Facebook JavaScript SDK calls that return or require an access token are only from HTTPS pages. If not all of your URLs are HTTPS or HSTS, you should update your pages to work over HTTPS and turn on the Enforce HTTPS setting in your Facebook Login settings.

To enforce HTTPS in redirects and for the JavaScript SDK:

• Go to the app dashboard, choose your app, and got to Facebook Login > Settings.
• Toggle the Enforce HTTPS setting to “yes.”

In the near future, this setting will be required.

Testing a Login Flow

It’s important to test and verify that your Facebook Login flow works well under a variety of conditions. To test your Login flow, first create a separate Facebook user account:

• Create a new test user account with Facebook
• Log into Facebook with your test user credentials

Common Test Cases – Before you test each use case below, make sure you remove your app from your test user’s Facebook account using app settings.

1. Someone new to your app logs in with Facebook

• Go to your app and tap on the Log in with Facebook button
• Tap OK to accept the read permissions
• Click OK again to accept write permissions if applicable
• Go to app settings and verify that the granted permissions are there

2. Someone logs in with Facebook after previously logging in via a non-Facebook flow with the same email address

• Go to your app and login using your email address
• Log out of your app and tap on the “Log in with Facebook” button
• Tap OK to accept the read permissions (and OK again to accept write permissions where applicable)
• Go to app settings on Facebook and verify that the granted permissions are there

3. Someone who has logged into your app with Facebook in the past logs back in

• Go back to your app and tap on the “Log in with Facebook” button
• Tap OK to accept the read permissions (and OK again to accept write permissions where applicable)
• Uninstall then re-install your app
• Open your app and tap on the “Log in with Facebook” button
• Verify that you can log in without seeing any permission dialogs

4. Someone cancels log in with Facebook and tries to log in again

• Go to your app and tap on the “Log in with Facebook” button
• Verify that the read permissions are shown and tap “Cancel”
• Open your app and tap on the “Log in with Facebook” button
• Verify that the read permissions are shown again

5. Someone removes your app from Facebook via app settings and revisits your app. Your app should detect this and prompt the person to log back in.

• Go to your app and tap on the “Log in with Facebook” button
• Tap OK to accept the read permissions (and OK again to accept write permissions where applicable)
• Go to app settings on Facebook and remove your app
• Repeat steps 1-2 and verify that Facebook Login works

6. Someone changes the Facebook password after logging in with Facebook to your app

In this case, your token will be invalid and you should notify users that their Facebook session has expired and ask them to log in again.

• Change your Facebook password and select “Log me out of other devices”
• Go to your app and tap on the “Log in with Facebook” button
• Tap OK to accept the read permissions (and OK again to accept write permissions where applicable)
• Go to app settings on Facebook and verify that the granted permissions are there

7. Someone disabled Facebook platform via app settings and logs in to your app

In this case, you should make sure your app detects the error so that it can notify users and redirect them to the non-iOS integrated version of Facebook Login.

• Turn off platform for your test user via app settings
• Go to your app and tap on the “Log in with Facebook” button
• Tap OK to accept the read permissions (and OK again to accept write permissions where applicable)
• Verify that platform is now turned on and the app is added to your test user profile with correct privacy

8. For games that want to sync their status across multiple devices, test your syncing state

• Login with Facebook on your app and play your app’s game until you reach a certain level X
• Login with Facebook on a different device via the same or different operating systems, and test that level X remains

Best Practices

1. Prompt people to log in at the right time

If your app is well known and understood, you might be able to put your login button on the initial screen and still see decent conversion rates. If you do this, be sure the intro screen has a clear, succinct and compelling statement about what it has to offer:

A better option is to provide a glimpse of the content available to people prior to logging in, like the background photo in this example:

If your app requires additional education, you may want to offer a multi step demo above your login button. This gives people the option to either log in immediately or learn more first.

The best experience is to let people use your app and see its content before prompting them to log in. For example, many ecommerce sites such as Zulily don’t require people to log in until they’re ready to check out.

2. Only ask for the permissions you need

Only ask for the permissions you need. The fewer permissions you ask for, the easier it is for people to feel comfortable granting them. We’ve seen that asking for fewer permissions typically results in greater conversion.

You can always ask for additional permissions later after people have had a chance to try out your app.

An additional benefit of asking for fewer permissions is that you might not need to submit your app for App Review. You need to submit for App Review if you request any permissions other than public_profile and email.

3. Ask for permissions in context and explain why

You should trigger permission requests when people are trying to accomplish an action in your app which requires that specific permission.

For example, the Facebook app only asks for Location Services when people explicitly tap on the location button when updating their status.

In addition, people are most likely to accept permission requests when they clearly understand why your app needs that info to offer a better experience.

4. Use the button that comes with SDKs

The Facebook Login button that comes with our SDKs is easy to integrate and includes built-in education that ensures a consistent design and experience:

However, if you do decide to build your own, for best results follow the Facebook Platform Policy and the recommendations in the User Experience Design topic.

5. Avoid having people login from a WebView

Logging in from a WebView works only if people have the Facebook app installed on their mobile device. Because you cannot predict whether people will have the app installed, it’s better not to have them log in from a WebView.

6. Provide a way to log out

Once people are logged in, you should also give them a way to log out, disconnect their account, or delete it all together. In addition to being a courtesy, this is also a requirement of our Facebook Platform Policy.

The dating app Tinder, for example, gives you the option to log out or to delete your account entirely.

7. Test and measure

It’s incredibly important to test your Facebook Login flow under a variety of conditions, and we’ve built a robust testing plan for you to follow. It’s also a good idea to run qualitative usability tests to understand how people are reacting to what they see.

Once you’ve tested your Login flow and are ready to launch, we suggest using an analytics program to understand if people are completing the process and their overall conversion rates. Best practice apps can see conversion rates of over 80%. Facebook Analytics lets you monitor your conversion rates for free.

8. Follow the Facebook Platform Policy

To avoid potential problems later on, do a quick check to make sure your Login integration adheres to the login section of our policies.

9. Submit your app for App Review

You only need to submit your app for App Review if you’re requesting permissions beyond public profile and email. We recommend you submit your app for review as early as possible in your development lifecycle after you’ve integrated Facebook Login. You’ll receive transparent feedback during the App Review process, including feedback on changes you can make to get a denied permission approved, if appropriate. For existing apps, going through Login Review will not affect your current app.