Authentication and Access Tokens

OAuth 2 is a secure protocol for allowing your users to authenticate to FamilySearch. Four authentication mechanisms (“grant types”) are supported and described separately:

  • OAuth for Web Applications. Required for web applications, this grant type requires an authorization code to be obtained by directing the user to the authorization page and capturing the code from the result of the user's successful authentication. In order to obtain an access token for a web application, you will first need to call the authorization end point to get an authorization code. For more information, see the Authorization resource and RFC 6749, Section 4.1.
  • Unauthenticated Session. This grant type is used for API calls that don't require a user to log in. Only a few APIs accept unauthenticated access tokens.
  • OAuth for Native Clients. Used for mobile and desktop applications, this grant type allows the client to provide a user's username and password to obtain an access token, as specified by RFC 6749, Section 4.3. This grant type is restricted to approved application keys. To obtain approval, contact Developer Support.
  • Client Credentials. This grant type authenticates the service account associated with the client. It is restricted to approved application keys. To obtain approval, contact Developer Support.

For more information, see:

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/

OAuth for Web Applications

The authorization code grant type allows your users to authenticate to FamilySearch without having to share their usernames and passwords with your client. The process of obtaining an access token is detailed for a web-based application in the following figure and then discussed below. (The Sample App provided below also walks you through this authentication.)

Step 1: Register Your Client

Your client application must be registered with FamilySearch so that FamilySearch systems can identify it and authenticate it. (An automated way to manage your apps will be provided on this site soon, but in the meantime please continue to use the existing application form here.) When you have completed your registration, you will be issued an application key, a unique string that is used to identify your client to the FamilySearch API. In addition to supplying a description of your client when you register, you must also provide one or more redirect URIs to be associated with your client.

To register a redirect URI, email Developer Support and include your app key. You can register multiple URIs for the sake of development or different user flows. If you register more than one callback, then one must be designated the default. (Each client application is required to have its own key and associated redirect URI.)

Be aware that URIs registered on sandbox will not work on production. URIs for production need to be registered separately after you have been granted access to the system. You can use any valid URI that your computer can understand. Even "http://localhost:8080/oauth/token" would work if that’s how your app was set up during development.

Step 2: Authenticate The User

Users are authenticated by being directed to the OAuth 2 authorization endpoint where they provide their credentials. The following query parameters must be sent:

Parameter Required Description
response_type Yes The type of response you want to receive after the user has authenticated. Use the value "code" for the authorization code grant type.
client_id Yes The identifier for your client is your app key.
redirect_uri Yes

The identifier for your client is your app key.

The URI to which the user will be redirected after authenticating. An authorization code is passed to this URI via query parameter as detailed in Step 3.

! The redirect URI must be pre-associated with your client ID. To register a redirect URI, email Developer Support and include your app key in the email.

state No See the OAuth 2 spec for details.

The URIs for the authorization endpoints for each reference system are listed below:

Reference URL
Sandbox https://sandbox.familysearch.org/cis-web/oauth2/v3/authorization
Staging https://identbeta.familysearch.org/cis-web/oauth2/v3/authorization
Production https://ident.familysearch.org/cis-web/oauth2/v3/authorization

Step 3: Capture the Authorization Result

After users have been brought through the authentication process, they are redirected to your client. Each redirect request includes some query parameters that detail the result of the authentication:

Parameter Description
code If the authentication was successful, an authorization code is issued and provided by this parameter.
error If the authentication was unsuccessful, this parameter provides an error code. Valid values include invalid_request, unauthorized_client, access_denied, and server_error and are detailed in the OAuth 2 spec.
error_description A human-readable message detailing the error upon an unsuccessful authentication
state See the OAuth 2 spec for details.

Step 4: Request an Access Token

The result of a successful authentication is an authorization code that is used to obtain an access token using the Access Token resource. This is done by POSTing a request to the token endpoint with the following parameters:

Parameter Required Description
grant_type Yes The type of authorization grant requested. The value must be “authorization_code” for the authorization code flow.
code Yes The authorization code for the web app.
client_id Yes The client identifier for your application is your app key.

The URI for the token endpoint depends on the reference system.

Reference URL
Sandbox https://sandbox.familysearch.org/cis-web/oauth2/v3/token
Staging https://identbeta.familysearch.org/cis-web/oauth2/v3/token
Production https://ident.familysearch.org/cis-web/oauth2/v3/token

Step 5: Process the Result

An access token is issued as the response to a successful request. Note that the response will be a JSON object with the following relevant properties:

Property Description
access_token If the request is successful, this property has the value of access token.
error If the request was unsuccessful, this property provides an error code. Valid values include invalid_request, unauthorized_client, access_denied, and server_error and are detailed in the OAuth 2 spec.
error_description A human-readable message detailing the error upon an unsuccessful authentication.

The body of an example response is as follows:

{
  ...

  "access_token":"2YotnFZFEjr1zCsicMWpAA",

  ...
}

Try It Out

The sample app will walk you through the process of getting an access token.

Unauthenticated Access Tokens

This token flow provides an access token that provides unauthenticated access. The level of access provided by an unauthenticated session is determined by service providers, which is also the case for authenticated access tokens.

Step 1: Register Your Client

Your client application must be registered with FamilySearch so that FamilySearch systems can identify it and authenticate it. (An automated way to manage your apps will be provided on this site soon, but in the meantime please continue to use the existing application form here.) When you have completed your registration, you will be issued an application key, a unique string that is used to identify your client to the FamilySearch API.

Step 2: Request an Access Token

Use the Access Token resource to obtain an Access Token by POSTing a request to the token endpoint with the following parameters:

Parameter Required Description
grant_type Yes Indicates that this is an unauthenticated token flow.
client_id Yes Contains the value identifying the client to the identity app.
client_secret Yes Required for confidential clients but not for public clients. It must NOT be set for public clients.
ip_address Yes Contains the IP address of the client and is used to identify if the user is within a certain group of IP addresses that will allow certain activities. Only needed for unauthenticated session grant type.

OAuth for Native Clients

The password grant type (such as "Resource Owner Password Credentials") allows the username and password of the resource owner to authenticate to FamilySearch with the access token returned directly from the call, as shown in the following figure. Note that permission to use this OAuth2 flow must be explicitly granted to each client.

Step 1: Register Your Client

Your client application must be registered with FamilySearch so that FamilySearch systems can identify it and authenticate it. (An automated way to manage your apps will be provided on this site soon, but in the meantime, please continue to use the existing application form here.) When you have completed your registration, you will be issued an application key, a unique string that is used to identify your client to the FamilySearch API. In addition to supplying a description of your client when you register, you must also request special permission to use the Password grant type.

Step 2: Request an Access Token

Use the Access Token resource to obtain an Access Token by POSTing a request to the token endpoint with the following parameters:

Parameter Required Description
grant_type Yes The type of authorization grant requested. The value must be “password” for the password grant type.
client_id Yes The client identifier for your application is your app key.
username Yes The resource owner's username.
password Yes The resource owner's password.

The URI for the token endpoint depends on the reference system.

Reference URL
Sandbox https://sandbox.familysearch.org/cis-web/oauth2/v3/token
Staging https://identbeta.familysearch.org/cis-web/oauth2/v3/token
Production https://ident.familysearch.org/cis-web/oauth2/v3/token

Step 3: Process the Result

An access token is issued as the response to a successful request. Note that the response will be a JSON object with the following relevant properties:

Property Description
access_token If the request is successful, this property has the value of access token.
error If the request was unsuccessful, an error code is provided via this property. Valid values include invalid_request, unauthorized_client, access_denied, and server_error and are detailed in the OAuth 2 spec.
error_description A human-readable message detailing the error upon an unsuccessful authentication.

The body of an example response is as follows:

{
  ...

  "access_token":"2YotnFZFEjr1zCsicMWpAA",

  ...
}

Client Credentials

This token flow provides provides clients with authenticated access to a service account. This flow is only available to confidential clients.

Step 1: Register your Client

Your client application must be registered with FamilySearch so that FamilySearch systems can identify it and authenticate it. (An automated way to manage your apps will be provided on this site soon, but in the meantime, please continue to use the existing application form here.) When you have completed your registration, you will be issued an application key, a unique string that is used to identify your client to the FamilySearch API.

Step 2: "Elevate" the application key

Elevate the app key by generating a public-private key pair and send the public key to FamilySearch.

Step 3: Request an Access Token

Use the Access Token resource to obtain an Access Token by POSTing a request to the token endpoint using the parameters below. The client is identified by requiring the client to create and sign a timestamp.

Parameter Required Description
grant_type Yes This value must be set to "client_credentials".
client_id Yes Contains the value identifying the client to the identity application. This value must be set to the client's app key.
client_secret Yes Contains the secret used to validate a confidential client. Required for confidential clients but not for public clients. It must NOT be set for public clients. To create a client_secret:
  1. Create the timestamp, which is a decimal string indicating the time in milliseconds since January 1, 1970 00:00:00 GMT.
  2. Use the RSA-SHA512 algorithm to encrypt (sign) the timestamp using the private key. Then Base64 encode the timestamp. The resulting alphanumeric string is used for the signature.
  3. The client_secret is displayed as [signature]:[timestamp] and is submitted as the client_secret paramater.

Click here to see a javascript example of using the client_credentials flow.

Refresh tokens are credentials used to obtain access tokens without user interaction. You must have a confidential client in order to use a refresh token. FamilySearch needs to grant access to your client to use the refresh token, and the user has to request an extended log-in.