OAuth Dialog

Use the OAuth dialog within the login flows to enable people to log in with your app. You also use it when you need people to grant additional permissions to your app. Facebook's authentication flows are based on the OAuth 2.0 protocol.

While the dialog can be invoked using the JS SDK, the iOS SDK and the Android SDK, it can also be invoked directly by opening a URL in a web browser.

Constructing a URL to the OAuth dialog

To invoke the OAuth dialog, redirect the browser to a URL of the form:

http://www.facebook.com/dialog/oauth/?
    client_id=YOUR_APP_ID
    &redirect_uri=YOUR_REDIRECT_URL
    &state=YOUR_STATE_VALUE
    &scope=COMMA_SEPARATED_LIST_OF_PERMISSION_NAMES

Parameters

The OAuth dialog supports the following parameters, which can be passed in the URL string:

Parameter	Required?	Description
client_id	Yes*	Your App ID. This is called client_id instead of app_id for this particular method in order to be compliant with the OAuth 2.0 specification.
redirect_uri	Yes*	Should not be set when using the JS SDK to invoke the dialogsThe URL to redirect to after a button is clicked or tapped in the dialog. The URL you specify must be a URL of with the same Base Domain as specified in your app's settings, a Canvas URL of the form https://apps.facebook.com/YOUR_APP_NAMESPACE or a Page Tab URL of the form https://www.facebook.com/PAGE_USERNAME/app_YOUR_APP_ID
scope	No	A comma separated list of permission names which you would like people to grant your app. Only the permissions people have not already granted your app will be shown
state	No	A unique string used to maintain app state between the request and callback. When Facebook redirects people back to your redirect_uri, this parameter's value will be included in the response. You should use this to protect against Cross-Site Request Forgery.
response_type	No	The requested response type, one of code or token. Defaults to code. If left unset, or set to code the dialog response includes an OAuth code that can be exchanged for an access token as per the server-side authentication flow. If set to token, the dialog response includes an oauth user access token in the fragment of the URL the browser is redirected to - as per the client-side authentication flow.
display	No	The display mode with which to render the dialog. One of page, popup or touch. Defaults to page in a desktop browser or if the dialog is invoked on the www.facebook.com domain. Defaults to touch in a mobile browser or when the dialog is invoked on the m.facebook.com domain. No other display type is allowed on m.facebook.com. In page mode, the OAuth dialog is displayed in the full Facebook chrome. In 'popup' mode, the OAuth dialog is displayed in a form suitable for embedding in a popup window. This parameter is automatically specified by most Facebook SDK, so may not need to be set explicitly.

*Important: When using the JS SDK, do not specify client_id or redirect_uri - these will be set by the SDK.

Return values

If people authorize your app, the browser redirects to the URL you specified in the redirect_uri parameter.

If the response_type was left unset or was set to the value code, if people authorize your app, the browser redirects to:

YOUR_REDIRECT_URI?       
     code=OAUTH_CODE_GENERATED_BY_FACEBOOK
    &state=YOUR_STATE_VALUE

See the server-side authentication documentation for how to exchange this code for a user access token.

If the response_type was the value token, if people authorize your app, the browser is redirected to:

YOUR_REDIRECT_URI#
    access_token=USER_ACCESS_TOKEN
   &expires_in=NUMBER_OF_SECONDS_UNTIL_TOKEN_EXPIRES
   &state=YOUR_STATE_VALUE

See the client-side authentication documentation for more on how to handle this response.

If people do not authorize your app, the browser is redirected to:

YOUR_REDIRECT_URI?
    error_reason=user_denied
   &error=access_denied
   &error_description=The+user+denied+your+request.
   &state=YOUR_STATE_VALUE