Authenticate

Warning: OAuth 1.0 has been deprecated in favor of OAuth 2.0.

The Authenticate service performs user authentication after an Initialize call, and creates a session that is required by all of FamilySearch APIs.

After a certain number of failed login attempts the user will be locked out for a period of time.

URI

https://api.familysearch.org/identity/v2/authenticate

HTTP Method

GET, POST

Parameters

&username=: The FamilySearch user name (sign-in name). You can pass this either as a parameter on a POST request or in the HTTP header using HTTP Basic Authentication on a GET request.
&password=: The FamilySearch password. You can pass this either as a parameter on a POST request or in the HTTP header using HTTP Basic Authentication on a GET request.

&sessionId=

To promote your session into an authenticated session. Pass in the sessionId you got from calling the initialize endpoint.

Response

After a user has signed in successfully, the family tree will return the session id in the body of the response. It will be the same sessionId you received from the initialize call. The only difference is that this sessionId has now been promoted to an authenticated sessionId.

Use the sessionId parameter to include this session id with all requests.

Errors

Error	Possible Causes	API-Specific Examples	Implemented
310	The user needs to go to the family tree and perform some action, such as read a new version of the conditions of use.	A previously registered user needs to agree to new conditions of use before using API services.	Yes
400	Bad Request. Generic client error or multiple client errors.	Invalid agent Invalid payload or Basic Authorization header User name or password included in a GET request	Yes
401	Unauthorized. The user has invalid credentials or the session ID is missing, invalid, or has expired. This error also appears if the query string contains multiple question marks or the the session parameter contains letters in an incorrect case.	Wrong user name or password.	Yes
415	Unsupported data format, unsupported media type, invalid content-type in header, or invalid character encoding.	Post method uses wrong file format	No
431	Invalid developer key.		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
503	Service Unavailable. FamilySearch or the service that you are using is not currently available. Or you are being throttled.		Yes

Example 1: Using the GET Method

Request

GET https://api.familysearch.org/identity/v2/authenticate
  HTTP/1.1
  Authorization: Basic aGVhdG9ucmE6MTIzNHBhc3M=

Response

HTTP/1.0 200 OK\r\n
  Content-Type: text/xml;charset=UTF-8
  Set-Cookie: fssessionid=USYS3A4F6A6318EFA1F96AF16E1CB46D1214_ses001.app.prod.id;
   Domain=.familysearch.org; Path=/; Secure

  <?xml version="1.0" encoding="UTF-8"?>
  <identity xmlns="http://api.familysearch.org/identity/v2" version="2.7.20100604.5944" statusMessage="OK" statusCode="200">
    <session id="USYS3A4F6A6318EFA1F96AF16E1CB46D1214_ses001.app.prod.id"/>
  </identity>

Example 2: Using the POST Method