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.

   To receive a refresh token for native apps, please use PKCE and either the user needs to click the private computer checkbox or offline_access needs to be passed in with the list of scopes.

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, the Date Authority, Person Search, Person Matches Query, and Relationship Finder.

Client Credentials

Client credentials authentication can be granted to your app independent of the users who are using it. This is not available for general use. To obtain client credential authentication, you must first contact [email protected] to obtain special permission and assignment.

To obtain client credentials authentication call the Access Token API resource with client_credentials grant type and a client secret. The client secret is an encrypted or signed timestamp. For an example request and more information, see the Client Credentials Authentication document.

Open ID Connect

OpenID Connect, is a simple identity layer on top of the OAuth 2.0 protocol. OpenID Connect brings the following benefits to your user experience.

OpenID Connect enables your users to take advantage of their existing FamilySearch.org authenticated session. If the user is logged in on FamilySearch.org, it will not require the user to log in again. If the user was not previously logged in on FamilySearch, the process of logging in to obtain an access token will also initiate a FamilySearch.org session. This enables the user to follow links to the website without needing to re-authenticate for as long as the website session remains active.

Another benefit is that the POST to the Access Token Resource will return an Access Token and an Identity Token. The Identity Token contains profile information for the user. This can simplify your integration by eliminating the need for a subsequent call to the Current User Resource.

To use OpenID Connect with your integration, add the scope=openid query parameter to your Authorization request.

Identity scopes can be used to request claims for the identity token. You can request the following scopes: givenName, family_name, locale, gender, email, qualifies_for_affiliate_account, user_id, and country.

The profile scope returns givenName, family_name, gender, language and locale.

Example Redirect URL using an Identity Scope:

https://ident.familysearch.org/cis-web/oauth2/v3/authorization?response_type=code&scope=openid%20profile%20email%20country&client_id=a02j000000KTRjpAAH&redirect_uri=https://example.com/auth/

Example JWT ReturnedWhen using an identity scope (scope parameter), you'll receive a JSON Web Token (JWT) in the response to get an access token that will look like this:

{
   "access_token":"31c5b9fa-c934-47ed-90j1-c5a89n8f5326-aws-prod",
   "id_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
   "token_type":"Bearer"
}

To decode a JWT click here. To see sample code and a working prototype click here.

Note: When implementing OpenID Connect with the "scope" parameter, if you see the following error in the URL after you redirect to our Authentication URL, you will need to contact Developer Support and ask them to add a "realm" to your app key.

?error=invalid_request&error_description=Validation+exception.+Client+registration+required