Login
Warning: OAuth 1.0 has been deprecated in favor of OAuth 2.0.
Warning: Web applications may not use this service. They should use OAuth.
The Login service performs user authentication, communicates the product and version of the product making the API requests, 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/login
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.
- &agent=
- The name and version of the product calling the API, such as XYZ/2.02. You can pass this either as a parameter on a POST or GET request or in the HTTP header with the User-Agent value.
- &key=
- The application key.
Important: The username and password are never passed on the URL.
Application Key
This key is required. For example:
https://api.familysearch.org/identity/v2/login?key=MMMM-MMMM-MMMM-MMMM-MMMM-MMMM-MMMM-MMMM
Response
After a user has signed in successfully, the family tree will return the session id in the body of the response.
Use the sessionId parameter to include this session id with all requests.
Errors
| Error | Subcode |
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. |
|
Yes | |
| 400 |
1 |
Bad Request: Insufficient Query Information |
Yes |
|
| 400 |
2 |
Bad Request: Unable To Determine Location |
Yes |
|
| 400 |
5 |
Bad Request: Invalid Version |
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 |
|
| 401 |
0 |
Unauthorized: Unauthenticated |
Yes |
|
| 401 |
1 |
Unauthorized: Invalid User Credentials |
Yes |
|
| 401 |
2 |
Unauthorized: Invalid Session |
Yes |
|
| 401 |
3 |
Unauthorized: Invalid Key |
Yes |
|
| 401 |
4 |
Unauthorized: Invalid User Agent |
Yes |
|
| 401 |
5 |
Unauthorized: Registration Required |
Yes |
|
| 401 |
7 |
Unauthorized: Password Change Required |
Yes |
|
| 401 |
8 |
Unauthorized: Resolution Required |
Yes |
|
| 401 |
9 |
Unauthorized: Disabled User Account |
Yes |
|
| 401 |
10 |
Unauthorized: Account Not Activated |
Yes |
|
| 401 |
11 |
Unauthorized: Unauthorized |
Yes |
|
| 401 |
12 |
Unauthorized: Unauthorized in Area |
Yes |
|
| 401 |
13 |
Unauthorized: Unauthorized in Temple District |
Yes |
|
| 401 |
20 |
Unauthorized: Key Required |
Yes |
|
| 401 |
21 |
Unauthorized: Username Required |
Yes |
|
| 401 |
22 |
Unauthorized: Password Required |
Yes |
|
| 401 |
23 |
Unauthorized: No Session Found |
Yes |
|
| 401 |
24 |
Unauthorized: No User Agent Found |
Yes |
|
| 401 |
25 |
Unauthorized: No Originating IP Address Found |
Yes |
|
| 401 |
26 |
Unauthorized: Credentials Not Allowed on URL |
Yes |
|
| 401 |
50 |
Unauthorized: Authentication Service Unavailable |
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 application 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 (Please note that you must take the base 64 of your Username:Password)
GET /identity/v2/login?{key=} HTTP/1.1
Host: api.familysearch.org
User-Agent: XYZ/5.0
Authorization: Basic aGVhdG9ucmE6MTIzNHBhc3M=
Response
HTTP/1.1 200 OK 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
Request
POST /identity/v2/login HTTP/1.1 Host: api.familysearch.org Content-Type: application/x-www-form-urlencoded Content-Length: 80 username=jdoe&password=1234&agent=XYZ/1.0&key=MMMM-MMMM-MMMM-MMMM-MMMM-MMMM-MMMM
Response
HTTP/1.1 200 OK 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>