Authentication

The FamilySearch Authentication resource uses the OAuth 2 secure authentication protocol (OAuth) to allow apps to access FamilySearch data. Authentication is granted in the form of an access token. The following four authentication mechanisms or grant types are supported.

• Authorization Code Authentication for Web Apps, Desktop, and Mobile Apps. For the OAuth 2 specifications, see RFC 6749, Section 4.1.
• Unauthenticated Session. This grant type is used to obtain a limited use access token that can only be used for API calls that do not require a user to log in to FamilySearch. (Not all APIs accept unauthenticated access tokens)
• Client Credentials. This grant type authenticates the service account associated with the client. This is not available for general use.

For more information on OAuth 2 authentication, see the following references.

• OAuth Overview
• OAuth 2.0 Specification
• Libraries

Authorization Code Authentication for Web Apps

The authorization_code grant type uses an authorization code provided from a FamilySearch authorization page. This authorization code is then used to obtain an access token. Your app does not handle the username and password.

The process of obtaining an access token using an authorization code is detailed for web-based apps in the following graphic and procedure.

1. Authorization: Call the Authorization API resource.The user is directed to the FamilySearch login page to provide login credentials (username and password) and to accept the FamilySearch terms of access. You must supply a redirect URI as a parameter that is used to return from the login page to your app.

   An authorization code is sent back to the application.

2. Access Token: Call the Access Token API resource with authorization_code grant type and the authorization code as parameters. Below is an example that shows the parameters required. The redirect_uri parameter must be the same redirect URI that was used in the Authorization API request.

   Request

   POST /cis-web/oauth2/v3/token
   Accept: application/json
   Content-Type: application/x-www-form-urlencoded
   
   code=tGzv3JOkF0XG5Qx2TlKWIA&grant_type=authorization_code&redirect_uri=http%3A%2F%2Fflowerchildren.org%2Fauthentication%2Fredirect&client_id=PHNQ-DY47-PDAG-8NB9-XJD7-JE4J-R0W5-NK3P

   Response

   HTTP/1.1 200 OK
   Content-type: application/json
   X-processing-time: 3
   Vary: Accept,Accept-Language,Accept-Encoding,Expect
   Date: Sun, 03 Apr 1836 10:00:00 GMT-5
   Cache-control: no-cache, no-store, no-transform, must-revalidate, max-age=0
   Transfer-encoding: chunked
   
   {
     "access_token" : "2YoTnFdFEjr1zCsicMWpAA",
     "token_type" : "family_search"
   }

   An access token is returned to the app. This access token is then used as a parameter for all subsequent FamilySearch API resource requests.

   Native and mobile apps must also use PKCE.

Unauthenticated Session

The unauthenticated_session grant type offers limited access to FamilySearch data. There are a limited number of API resources that allow unauthenticated access. Call the Access Token API resource with unauthenticated_session grant type. See an example request that shows the parameters required.

An access token is returned to the app. This access token is then used as a parameter for all subsequent FamilySearch API resource requests.

The API resources that support unauthenticated sessions are Places and Standardized Dates.

Client Credentials

This is not available for general use.