Attention: This site does not support the current version of your web browser. To get the best possible experience using our website we recommend that you upgrade to a newer version or install another browser

Skip main navigation

FamilySearch 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. For the OAuth 2 specifications, see RFC 6749, Section 4.1.
  • Password Authentication for Desktop and Mobile Apps. For the OAuth 2 specifications, see RFC 6749, Section 4.3.
  • 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. Only a few 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.

Content Location
OAuth overview http://oauth.net/
OAuth 2.0 specification http://tools.ietf.org/html/rfc6749
Libraries for most languages to help implement the OAuth protocol http://oauth.net/2/

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. Authorize: 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. Authenticate: Call the Access Token API resource with authorization_code grant type and the authorization code as parameters. See an example request that shows the parameters required.

    The redirect_uri parameter must be the same redirect URI that was used in the Authorization API request.

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

Password Authentication for Desktop and Mobile Apps

The password grant type requires that your app obtains the username and password.

The process of obtaining an access token using a user name and password is detailed for desktop and mobile apps in the following graphic and procedure.

  1. Accept: Obtain the username, password, and acceptance of FamilySearch terms of access.
  2. DO NOT PROCEED if the user does not accept the terms of access. See the User Interface Suggestions in the Authenticate Desktop and Mobile App Users for FamilySearch Access topic.

  3. Authenticate: Call the Access Token API resource with password grant type and use the username and password as parameters. 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.

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, and Person Matches Query.

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 devsupport@familysearch.org 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 Returned

When 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

x

Select a language