Get Request Token
Warning: OAuth 1.0 has been deprecated in favor of OAuth 2.0.
Before your users can authenticate with FamilySearch systems, you must use your developer key to obtain a request token. The request token is a temporary token that tells the FamilySearch identity system that you have obtained user approval to authenticate. Later in the authentication process, the request token is exchanged, along with the OAuth Verifier, for an access token.
For details on obtaining an OAuth request token, see OAuth Core 1.0a, Section 6.1.
Parameters
- oauth_consumer_key
- Your developer key.
- oauth_nonce
- A random string (see OAuth Core 1.0a Spec, Section 8).
- oauth_signature_method
- The OAuth signature method. The value of this parameter will always be "PLAINTEXT". For more information on the plain text signature method, see OAuth Core 1.0a Spec, Section 9.4.
Note: Plain text can be used because the FamilySearch identity system also requires that all communication occur over SSL/TLS. - oauth_signature
- Because PLAINTEXT is the signature method and because the “consumer secret” is the empty string, the value of the signature will always be "%26" which is the encoded value of the consumer secret ("") concatenated with the token secret ("") by the '&' character. For details, refer to the OAuth Core 1.0a Spec, Section 9.4.
- oauth_timestamp
- Current timestamp of the request (number of seconds since January 1, 1970 00:00:00 GMT). This value must be +-5 minutes of the current time. (see OAuth Core 1.0a Spec, Section 8).
- oauth_callback
- The URL to which the identity system should redirect users. The callback is optional, but if provided, it will result in a significantly better user experience. After authenticating, users will be redirected to the callback, which is presumably controlled by the consumer application which can then take control of the user experience. If no callback is provided, users will be presented with a "success" screen that displays the verifier that they will have to provide to the consumer application.
- agent
- The user agent. This parameter can also be supplied via the standard HTTP header.
Response
The request token endpoint responds with the following information, in the format defined by the OAuth specification:
- oauth_token
- The request token.
- oauth_token_secret
- This secret associated with the request token. This secret will be later used in obtaining an access token.
Errors
| Error | Possible Causes | API-Specific Examples | Implemented |
|---|---|---|---|
| 400 | Bad Request. |
Invalid parameter values. | Yes |
| 401 | Unauthorized. Invalid developer key or no user agent supplied. |
|
Yes |
| 500 | Server Error. A generic server error or multiple server errors occurred. If you get this error, please report it through devsupport@familysearch.org. You can also post it to the FamilySearch Developer Network (FSDN). |
|
Yes |
Example 1: Using GET Method
Request (GET)
Response
https://api.familysearch.org/identity/v2/request_token?oauth_consumer_key=DEVKEY&oauth_nonce=123456789&oauth_signature_method=PLAINTEXT&oauth_signature=%26&oauth_timestamp=1252618480
oauth_token=E654B862352BF99451A91FFBB0EFF518&oauth_token_secret=17063cb9f3179fc0d8ef8768127b0428
Example 2: Using the POST Method
Request (POST)
https://api.familysearch.org/identity/v2/request_token
Request Payload
oauth_consumer_key=DEVKEY&oauth_nonce=123456789&oauth_signature_method=PLAINTEXT&oauth_signature=%26&oauth_timestamp=1252618480Response
oauth_token=E654B862352BF99451A91FFBB0EFF518&oauth_token_secret=17063cb9f3179fc0d8ef8768127b0428