API's » Genealogie Online Data API » Oauth2

The Genealogie Online Data API allows third-parties to access the users genealogical data. Authentication is handled using OAuth2. OAuth2 is a protocol that lets external apps (the 'client') request authorization to users data without getting their password. The following descibes how to get access.

Registering an application

Developers who want access for their application need to get approved by Coret Genealogie. Send application details like purpose, name, URL, logo (square) via e-mail. Once approved, Coret Genealogie will provide the following values to be used in the Oauth2 authentication calls:

• a unique client ID
• a unique client secret (which should be kept private!)

OAuth2 calls

The Genealogie Online Data API follows the OAuth2 protocol. The following URLs are used:

• https://www.genealogieonline.nl/oauth/authorize
• https://www.genealogieonline.nl/oauth/token

Web Application flow

1. Redirect the user to request access

GET https://www.genealogieonline.nl/oauth/authorize

This request is usually happens in the user's browser. On the authorisation screen, for which the user has to login on Genealogie Online, details about the application like name, logo and requests grants (in plain text) are shown.

Parameters

• response_type Required string

  Has to be of value code

• client_id Required string

  The client ID you received from Coret Genealogie.

• redirect_uri Optional string

  URL in your app where users will be sent after authorization. See details below about redirect urls.

• scope Optional string

  Space separated list of scopes. Default scope: basic, read more about scopes

• state Required string

  An unguessable random string. It is used to protect against cross-site request forgery attacks.

• lang Optional string

  Desired language for web interface: nl for Dutch (default), en for Engish, fr for French and de for German.

2. Genealogie Online redirects back to you

If the user accepts your request, Genealogie Online redirects back to your redirect URL with a temporary code in a code parameter as well as the state you provided in the previous step in a state parameter. If the states don't match, the request has been tampered with and the process should be aborted.

GET https://your-site.com/authorized?code={code}&state={state}

If the user did not accept your request, Genealogie Online redirects back to your redirect URL with an error access_denied

GET https://your-site.com/authorized?error=access_denied&error_description=The+user+denied+access+to+your+application

Exchange the temporary code for an access token:

POST https://www.genealogieonline.nl/oauth/token

This request is done server to server:

curl -X POST https://www.genealogieonline.nl/oauth/token -d 'grant_type=authorization_code&code=...&client_id=...&client_secret=...'

Parameters

• grant_type Required string

  Has to be value authorization_code

• code Required string

  The code you received as a response in first step.

• client_id Required string

  The client ID you received from Coret Genealogie.

• client_secret Required string

  The client secret you received from Coret Genealogie.

• redirect_uri Required string

  URL in your app where users will be sent after authorization.

Response

By default, the response will take the following form:

{
  "access_token":"3e2de69ee40b74eee3d00a07f54d2c7d7ba5efb1",
  "expires_in":3600,
  "token_type":"bearer",
  "scope":"basic gedcom",
  "refresh_token":"c1dc1403dfddac1cab6d0a0c6f9c71da3e8b50f2"
}

3. Use the access token

The access token allows you to make requests to the Genealogie Online Data API on a behalf of a user. The access token can be provided as parameter in the URL or as HTTP header.

Parameters for GET requests

GET https://api.genealogieonline.nl/v1/publications?access_token=...

HTTP headers for GET (POST, PUT, DELETE and PATCH) requests

GET https://api.genealogieonline.nl/v1/publications

• Authorization Required string

  Has to be value Bearer access_token

4. Access token expiration

The access token has only a relatively short lifetime before it expires (3600 seconds). This is due to it's nature as it is send openly with every request and it could be intercepted.

When you get the message:

{"error":"invalid_grant","error_description":"The access token provided has expired"}

You have to catch this and get a new access_token by using the refresh_token first.

POST https://www.genelogieonline.nl/oauth/token

Parameters

• grant_type Required string

  Has to be value refresh_token

• refresh_token Required string

  The refresh token you received with the first access token

• client_id Required string

  The client ID you received from Coret Genealogie.

• client_secret Required string

  The client secret you received from Coret Genealogie.

Response

The response will bring a fresh access token

{
  "access_token":"cc0d632e7be14bae03f9384accefadc1fc868b81",
  "expires_in":3600,
  "token_type":"bearer",
  "scope":"basic gedcom"
}

With this new access token you can continue sending requests.

5. Error Responses

The OAuth2 error responses have always the same format with error defining the type of errer and error_description being more detailed about the missing requirements.

Example:

{
  "error":"invalid_grant",
  "error_description":"The access token provided has expired"
}

Possible Errors

• invalid_request

  The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.

  Possible detailing desciptions:

  • Invalid or missing response type: Response type can be of value code
  • Missing parameter: "code" is required
  • Missing parameter: "refresh_token" is required
  • Authorization code doesn't exist or is invalid for the client
  • The access token was not found
  • Invalid refresh token
  • Malformed auth header
  • Only one method may be used to authenticate at a time (Auth header, GET or POST)
  • When putting the token in the body, the method must be POST
  • The grant type was not specified in the request: Grant type can be of value authorization_code or refresh_token

• invalid_grant

  The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.

  Possible detailing desciptions:

  • The access token provided is invalid
  • The access token provided has expired
  • Malformed token (missing "expires" or "client_id")
  • The user you requested the token for is not valid
  • An unsupported scope was requested.

• invalid_client

  Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method).

  • No client id supplied'
  • Client credentials were not found in the headers or body
  • The client credentials are invalid

• insufficient_scope

  • The request requires higher privileges than provided by the access token

• invalid_uri

  • The redirect URI must not contain a fragment

• access_denied

  • The user denied access to your application

• invalid_scope

  The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.

  • An unsupported scope was requested

Scopes

Scopes let you specify exactly what type of access you need. Scopes limit access for OAuth tokens. They do not grant any additional permission beyond that which the user already has. The requested scopes will be displayed to the user on the authorize form.

There are two scopes defined:

• basic

  This scope allows the application to view the users genealogical publications, including public persons, images, starting points and stories on Genealogie Online.

• gedcom

  This scope allows the application to download the GEDCOM file(s) you provided to Genealogie Online.