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.

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.

If you feel this is a desirable option for your app, please contact devsupport@familysearch.org.

Client Credentials

Client credentials authentication can be granted to your app independent of the users who are using it. If you need client credentials authentication, please contact devsupport@familysearch.org to have your app key enabled for client credentials.

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.