Auth.getSession
From Facebook Developers Wiki
Contents |
[edit] 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.
[edit] Parameters
| Required | Name | Type | Description | |
| required | api_key | string | The application key associated with the calling application. | |
|---|---|---|---|---|
| sig | string | An MD5 hash of the current request and your secret key, as described in the authentication guide. | ||
| v | string | This must be set to 1.0 to use this version of the API. | ||
| auth_token | string | The token returned by auth.createToken and passed into login.php | ||
| optional | format | string | Desired response format. Either XML (default) or JSON. | |
| 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 non-infinite sessions, for applications that want to use a client-side component without exposing the application secret. Note that the app secret will continue to be used for all server-side calls, for security reasons. |
[edit] 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> |
[edit] Example Return JSON
| {"session_key":"5f34e11bfb97c762e439e6a5-8055","uid":"8055","expires":1173309298} |
[edit] 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 the authentication guide 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.
[edit] 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. |
[edit] 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.
Note also that this function does not require a session_key or call_id (although specifying a call_id does not cause any problems). The session key can be stored for the duration of the session, and the uid can be stored indefinitely.
