Oauth2

The Genealogie Online Data API allows third-parties to access the users genealogical data. Authorization 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:

OAuth2 calls

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


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


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

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


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

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


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: