Home
Developer Portal
Apply to collaborate with us

Token Refresh

August 16, 2024

Token Request with Refresh Token

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.

The Token Request can be made with a Refresh Token to acquire new tokens. This is discussed in Section 6 of the RFC 6749 OAuth 2.0 Spec.

The format of the Token Request will be very similar to the request referenced in the above Token Request section, but the parameters will be as such.

ParameterValue
grant_typeThis must be set to refresh_token.
refresh_tokenThis should be set to the value of your current Refresh Token.

A successful request will receive a response with a new set of tokens. Your app should discard the used Refresh Token and keep the new token for the next refresh.
Example Request

POST /cis-web/oauth2/v3/token HTTP/1.1
Host: ident.familysearch.org
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=-84169492-45-40-107571079511378-2089-7-1108766-34-4620883010-8022-8110215-4-1-103

Example Response

HTTP/1.1 200 OK
Date: Tue, 03 Nov 2020 22:29:44 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 694
Connection: keep-alive
Cache-Control: no-store, no-cache, must-revalidate, max-age=0, post-check=0, pre-check=0
Content-Encoding: gzip
Content-Language: en-US
Expires: Tue, 03 Jul 2001 06:00:00 GMT
Last-Modified: Tue Nov 03 22:29:44 UTC 2020
Pragma: no-cache
Server: nginx/1.18.0
X-Robots-Tag: noindex, nofollow, noarchive, nosnippet, notranslate, noimageindex

{
    "access_token": "8060ac21-72c8-444b-9845-d9cfd31af525-integ",
    "id_token": "eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJodHRwczpcL1wvaW50ZWdyYXRpb24uZmFtaWx5c2VhcmNoLm9yZ1wvc2VydmljZVwvaWRlbnRcL2Npc1wvY2lzLXdlYlwvb2F1dGgyXC92MyIsInN1YiI6ImNpcy51c2VyLk1NTU0tRERIMiIsImF1ZCI6ImEwMmYxMDAwMDBTU3hLTUFBMSIsInNlc3Npb25JZCI6IjgwNjBhYzIxLTcyYzgtNDQ0Yi05ODQ1LWQ5Y2ZkMzFhZjUyNS1pbnRlZyIsImV4cCI6MTYwNDUyNzI0MCwiaWF0IjoxNjA0NTIwMDQwfQ.WvGpCcY1kfi2hvHseJqePmZGrbEMU8tmsSs9IpcvPacuwcevGhIczSGCB_51JdBXMFIicKgowt8lj_k5CYt7ATQjxz1ICiTkvBJsM_xaPcAAkPcN65OKdxxhaStBGypkyrMPDAfP_X3UbXHLJ_EDbG5ffW0JnnM8c-5RIhbhjRLypFEc1kPjLKtlVbOuHt9kPcIkDzzdtiZEQQRnI7nabN9NQbN8bmrv6xexIJgeBAc9iybWMM3x_NsXd9zfKsxPNosjTj0QovAh2JrJSCpHXwimst2YWCe6Rs7PXloI9UDpNcDlPbiwhPdhqpMOIp8zUoGMNeBz0-MUfrElpseqcg",
    "refresh_token": "11725-3632127-8773105-8620-58120-97-5086-116117-61-8510384-9058735-50-1217-17826",
    "token_type": "Bearer"
}

Requirements and Best Practices

Please observe the following requirements and best practices.

Requirements

  1. Native applications must use PKCE as part of the authorization process.
  2. The Authorization flow must be performed by the system's default web browser.
    1. In the case of iOS, it is acceptable to use SFSafariViewController.
    2. In the case of Android, it is acceptable to use Chrome Custom Tabs in Chrome 45+.

Best Practices

When using the loopback address for redirect, it is advised to:

  1. Use http://127.0.0.1:{port} (IP v4) or http://[::1]:{port} (IP v6) instead of localhost. Using localhost has been known to cause problems with some client firewalls.
  2. Use a port number greater than 1024 to avoid conflict with reserved ports and to avoid Windows UAC privileged user requirements.

Helpful Implementation Resources