OAuth Dialog

The OAuth Dialog is used within the authentication flows to enable a user to authorize your application and 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 the user's web browser.

Constructing a URL to the OAuth Dialog

To invoke the OAuth Dialog, redirect the user's 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 may 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 the user clicks a button 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 the user to grant your application. Only the permissions which the user has not already granted your application will be shown
state	No	A unique string used to maintain application state between the request and callback. When Facebook redirects the user 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's response will include an OAuth code which can be exchanged for an access token as per the server-side authentication flow. If set to token, the Dialog's response will include an oauth user access token in the fragment of the URL the user 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 when the user is using a desktop browser or the dialog is invoked on the www.facebook.com domain. Defaults to touch when the user is using a mobile browser or 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 the user authorizes your application, the browser will redirect 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 the user authorizes your application, the browser will be redirected 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 the user authorizes your application, the browser will be 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 the user does not authorize your application, the browser will redirect to

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