Auth.getSession
From Facebook Developer Wiki
Contents |
Description
Returns the session key bound to an auth_token, as returned by auth.createToken or in the callback_url. Should be called immediately after the user has logged in or connected accounts with your Facebook Connect site.
Parameters
| Required | Name | Type | Description | |
| required | api_key | string | The application key associated with the calling application. If you specify the API key in your client, you don't need to pass it with every call. | |
|---|---|---|---|---|
| sig | string | An MD5 hash of the current request and your secret key, as described in the How Facebook Authenticates Your Application. Facebook computes the signature for you automatically. | ||
| v | string | This must be set to 1.0 to use this version of the API. If you specify the version in your client, you don't need to pass it with every call. | ||
| auth_token | string | The token returned by auth.createToken and passed into login.php | ||
| optional | format | string | The desired response format, which can be either XML or JSON. (Default value is XML.) | |
| callback | string | Name of a function to call. This is primarily to enable cross-domain JavaScript requests using the <script> tag, also known as JSONP, and works with both the XML and JSON formats. The function will be called with the response passed as the parameter. | ||
| generate_session_secret | bool | Whether to generate a temporary session secret associated with this session. This is for use only with regular sessions where the user hasn't granted your site or application the offline_access extended permission, for applications and sites that want to use a client-side component without exposing the application secret. Note that the application secret is still required for all server-side calls, for security reasons. | ||
| host_url | string | The full URL of the page being constructed. By providing the host URL, we can determine what base domain to use when setting cookies on the client's browser. |
Response
If the user has successfully logged in, this returns valid values for each field. The expires element is a Unix time that indicates when the given session expires. If the value is 0, the session never expires. See Authorizing Applications for more information.
For desktop applications, the top-level element auth_getSession_response has an additional element named secret that should be used as the session's secret key as described in the authentication guide.
Example Return XML
<?xml version="1.0" encoding="UTF-8"?>
<auth_getSession_response
xmlns="http://api.facebook.com/1.0/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://api.facebook.com/1.0/ http://api.facebook.com/1.0/facebook.xsd">
<session_key>5f34e11bfb97c762e439e6a5-8055</session_key>
<uid>8055</uid>
<expires>1173309298</expires>
</auth_getSession_response>
Example Return JSON
{"session_key":"5f34e11bfb97c762e439e6a5-8055","uid":"8055","expires":1173309298}
Error Codes
| Code | Description | |
| 1 | An unknown error occurred. Please resubmit the request. | |
|---|---|---|
| 2 | The service is not available at this time. | |
| 4 | The application has reached the maximum number of requests allowed. More requests are allowed once the time window has completed. | |
| 5 | The request came from a remote address not allowed by this application. | |
| 100 | One of the parameters specified was missing or invalid. For example, not passing auth_token to login.php can cause this error. | |
| 101 | The API key submitted is not associated with any known application. | |
| 104 | Incorrect signature. |
Notes
- For desktop applications this method should be called at the https endpoint instead of the http endpoint, and its return value is slightly different (as noted above). It is worth to be noted that this method will still work even if it is called at the http endpoint, but it is less secure.
- This method does not require a
session_keyorcall_id(although specifying acall_iddoes not cause any problems). The session key can be stored for the duration of the session, and theuidcan be stored indefinitely.
- For Facebook canvas pages, the session key is passed to your page using POST with the
fb_sig_session_keyparameter.
