Authentication Guide

MyHeritage implements draft 16 of the OAuth 2.0 protocol, with bearer token support. We currently implemented the server-side and device flows.

OAuth 2.0 flows

OAuth 2.0 for server-side web applications

This flow is meant for web applications with servers that can keep secrets and maintain state. For those who prefer to send and receive HTTP directly without using a client library, this section walks through how to use OAuth 2.0 for server-side web applications with MyHeritage.

The server-side flow has two parts. In the first part, your application asks the user for permission to access his data - if the user approves, MyHeritage will send your application an authorization code. In the second part, your application will POST that code along with its client secret to MyHeritage in order to get an access token.

Getting a user's permission

Redirect your users to our authorization page at

https://accounts.myheritage.com/oauth2/authorize

with the following query parameters:

Parameter	Description
client_id	(required) This is how MyHeritage identifies your application - MyHeritage will give you a client_id when you register your app with MyHeritage.
redirect_uri	(required) The URL on your site that will handle OAuth responses after the user takes an action on the dialog. You'll need to register the redirect_uri you'd like to use in advance. See the Get access page for details on how to register.
scope	(optional) A comma-separated list of the requested scopes. The basic scope is always requested and does not have to be listed here explicitly.
response_type	(required) Currently only code is supported, for the server-side flow.
state	(optional) A string used to maintain state between the request and redirect. This value will be appended to your redirect_uri after the user takes an action on the OAuth dialog.

Here's an example URL for an application running on www.example.com:

https://accounts.myheritage.com/oauth2/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=http://www.example.com/back&
  scope=basic&
  response_type=code

After the user approves access or chooses not to, we'll redirect to the redirect_uri you passed us and append either an authorization code or an error message in a query parameter. For example, in the example above if a user denies access, we'll redirect to:

http://www.example.com/back?error=access_denied&error_description=The+user+denied+your+request

And if the user approves access:

http://www.example.com/back?code=1560ca2f381591b83696f947d174a99b

Your webserver should swap that authorization code for a refresh token and access token pair by POSTing it along with your client_id, client_secret and grant_type=authorization_code to our OAuth 2.0 token endpoint:

https://accounts.myheritage.com/oauth2/token

This request might look like:

POST /oauth2/token HTTP/1.1
Host: accounts.myheritage.com
Content-Type: application/x-www-form-urlencoded

code=1560ca2f381591b83696f947d174a99b&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
redirect_uri=http://www.example.com/back&
grant_type=authorization_code

You can try out that call using the curl command line application, substituting the code you got from the above example URL - note that you may need to urlencode your redirect and secret, as curl won't automatically do that for you:

curl https://accounts.myheritage.com/oauth2/token -d "code=1560ca2f381591b83696f947d174a99b&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&redirect_uri=http://www.example.com/bac&grant_type=authorization_code"

We'll return a short-lived access token in a JSON object:

{
    "access_token":"6e51bc6d59addac9e7fc47f2c3cc0b80",
    "expires_in":7200,
    "token_type":"Bearer",
    "refresh_token":"5ef41db6d4c35f64a42ac669ca64c188"
}

Using your access token

You can use your access token to call a protected API by including it in a bearer_token query parameter or an Authorization header. For example, you can use the curl command-line application to call the Family Graph API with the access token you got above:

curl https://familygraph.myheritage.com/me?bearer_token=6e51bc6d59addac9e7fc47f2c3cc0b80

See the Calling a protected API section for the full details.

Refresh your access token

When your access_token is expired you can get a new one using your refresh_token. This can be done by POSTing your refresh_token along with your client_id, client_secret and grant_type=refresh_token to our OAuth 2.0 token endpoint:

https://accounts.myheritage.com/oauth2/token

This request might look like:

POST /oauth2/token HTTP/1.1
Host: accounts.myheritage.com
Content-Type: application/x-www-form-urlencoded

refresh_token=5ef41db6d4c35f64a42ac669ca64c188&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
grant_type=refresh_token

You can try out that call using the curl command line application,

curl https://accounts.myheritage.com/oauth2/token -d "refresh_token=5ef41db6d4c35f64a42ac669ca64c188&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=refresh_token"

OAuth 2.0 for client-side web applications

This flow is meant for client-side web applications that cannot keep secrets and maintain state. This section walks through how to use OAuth 2.0 for client-side applications with MyHeritage.

This scenario begins by redirecting a browser to a URL on MyHeritage which eventually asks the user for permission to access his data. Like in the server-side flow, MyHeritage handles the user authentication and the result is an access token. MyHeritage returns the results on the fragment of the response and the client-side script should extract it from there.

Getting a user's permission

Redirect your users to our authorization page at

https://accounts.myheritage.com/oauth2/authorize

with the following query parameters:

Parameter	Description
client_id	(required) This is how MyHeritage identifies your application - MyHeritage will give you a client_id when you register your app with MyHeritage.
redirect_uri	(required) The URL on your site that will handle OAuth responses after the user takes an action on the dialog. You'll need to register the redirect_uri you'd like to use in advance. See the Get access page for details on how to register.
scope	(optional) A comma-separated list of the requested scopes. The basic scope is always requested and does not have to be listed here explicitly.
response_type	(required) Currently only token is supported, for the client-side web application flow.
state	(optional) Indicates any state which may be useful to your application upon receipt of the response. The server round trips this parameter, so your application receives the same value it sent.

Here's an example URL for an application running on www.example.com:

https://accounts.myheritage.com/oauth2/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=http://www.example.com/back&
  scope=basic&
  response_type=token

After the user approves access or chooses not to, we'll redirect to the redirect_uri you passed us and append access token or an error message in the fragment. For example, in the example above if a user denies access, we'll redirect to:

http://www.example.com/back#error=access_denied&error_description=The+user+denied+your+request

And if the user approves access:

http://www.example.com/back#access_token=6e51bc6d59addac9e7fc47f2c3cc0b80&expires_in=7200&token_type=Bearer

Using your access token

You can use your access token to call a protected API by including it in a bearer_token query parameter or an Authorization header just like in the server-side flow. See the Calling a protected API section for the full details.

OAuth 2.0 for devices

This flow is meant for applications running on devices that have an internal web-browser, cannot keep secrets and are able to maintain state. For those who prefer to send and receive HTTP directly without using a client library, this section walks through how to use OAuth 2.0 for applications on devices with MyHeritage.

Your application begins this flow in a browser which eventually asks the user for permission to access his data. In the meantime your application may begin polling for an access token and a refresh token. These tokens will be returned only if the user approves, otherwise an error will be returned.

Getting a user's permission

Redirect your users to our authorization page at

https://accounts.myheritage.com/oauth2/authorize

with the following query parameters:

Parameter	Description
client_id	(required) This is how MyHeritage identifies your application - MyHeritage will give you a client_id when you register your app with MyHeritage.
redirect_uri	(required) The redirect_uri for devices must be urn:ietf:wg:oauth:2.0:oob. This value indicates that the device is out-of-bounds and instead of returning to a specific URL the results will be displayed in the browser. You'll need to register the redirect_uri in advance. See the Get access page for details on how to register.
scope	(optional) A comma-separated list of the requested scopes. The basic scope is always requested and does not have to be listed here explicitly.
response_type	(required) Currently only token is supported, for the device flow.
state	(optional) Indicates any state which may be useful to your application upon receipt of the response. The server round trips this parameter, so your application receives the same value it sent.

Here's an example URL for an application running on a device:

https://accounts.myheritage.com/oauth2/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=urn:ietf:wg:oauth:2.0:oob&
  scope=basic,offline_access&
  response_type=token

After the user approves access or chooses not to, we'll display the results in the browser. For instance, in the example above if a user denies access, a web-page with the following title will be returned:

Error error=access_denied&error_description=The+user+denied+your+request

And if the user approves access the title will be:

Success access_token=6e51bc6d59addac9e7fc47f2c3cc0b80&expires_in=7200&token_type=Bearer

Your device should poll the browser and look for a title change. Once the Success or Error prefix is detected in the title it means that the authorization process is done and the results will reside right after the first title space character. Note that the results are encoded as a query string.

Using your access token

You can use your access token to call a protected API by including it in a bearer_token query parameter or an Authorization header just like in the server-side flow. See the Calling a protected API section for the full details.

Calling a protected API

After your application has obtained an access token, your app can use it to access APIs by including it in either a bearer_token query parameter or an Authorization: Bearer header. Because we use bearer tokens in our implementation of OAuth 2.0, no additional credentials are required.

For example, a call to the Family Graph API using the bearer_token query parameter might look like the following:

GET https://familygraph.myheritage.com/me?bearer_token=YOUR_ACCESS_TOKEN

and using the Authorization: Bearer header:

GET /me HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Host: familygraph.myheritage.com

You can try either out with curl, a command-line application for HTTP. Here's an example of the query parameter:

curl https://familygraph.myheritage.com/me?bearer_token=YOUR_ACCESS_TOKEN

And with the Authorization: Bearer header:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" https://familygraph.myheritage.com/me