Access Token

Description

The Access Token resource is used to obtain an access token to be used for the FamilySearch API.

An access token can be obtained through one of the following authentication mechanisms (i.e., "grant types"):

  • Authorization Code. This grant type is used by online web clients where a user can be directed to FamilySearch.org to provide credentials. 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. For more information, see the Authorization resource and RFC 6749, Section 4.1.
  • Username/Password (i.e., "Resource Owner Password Credentials"). This grant type is used by clients that cannot reasonably redirect a user to FamilySearch.org in a browser to provide credentials. 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 developer keys. To obtain approval, contact developer support.
  • Unauthenticated Session. This grant type allows the client to obtain an access token without requiring a user's credentials. Not all endpoints allow access via an unauthenticated session.

An access token is obtained by issuing a POST request to the Access Token resource with the parameters appropriate to the grant type being used. The result of a successful request will be a JSON object containing (among other things) the access token as described by RFC 6749, Section 4.

Failure to obtain an access token will result in a response as described in RFC 6749, Section 5.2.

The Access Token resource is also used to DELETE an access token, which is done by issuing a DELETE request with the access token passed as a query parameter.

Data Formats

If you make a GET request, specify the data format using the Accept header.

If you POST something, specify the media type using the Content-Type header.

  • application/x-www-form-urlencoded
  • application/json

Parameters

Name Type Description
username form The username. (Not required for the authorization code or unauthenticated session grant type.)
grant_type form The grant type, which MUST be either "authorization_code", "password", or "unauthenticated_session".
code form The authorization code. Not required for the username/password or unauthenticated session grant type.)
password form The password. (Not required for the authorization code or unauthenticated session grant type.)
client_id form The application key (i.e., "client id").
ip_address form The client ip address. (Not required for the username/password or authorization code grant type.)
access_token query The access token. This parameter is only used when invalidating (deleting) an access token.

Operations

POST - Request an OAuth 2.0 access token.

Status Codes
200 When the request for an access token was successful.
400 If there is an error upon a request for an access token.

DELETE - Delete the access token, causing the authorized session to cease, and the access token becomes invalid.

Status Codes
204 Upon a successful delete or has already been invalidated.
404 Access token parameter is missing.

Example Requests

Delete Access Token How to invalidate an access token.
Obtain Access Token (Bad Parameters) Example of invalid parameters when exchanging the authorization code for an access token.
Obtain Access Token with Authorization Code How to exchange an authorization code for an access token.
Obtain Access Token with Username and Password How to exchange a user's username and password for an access token.
Obtain Access Token without Authenticating How to obtain an access token without authenticating.