1. clientLogin

The first step is for you to send the user to https://api.wikitree.com where they can login with their WikiTree email and password. That form will send you back here with an authorization code. For them to land back here, we need to set a returnURL parameter.

2. Confirm clientLogin with authcode

When the API redirects back here (i.e. to returnURL), it appends the parameter authcode. See the current page's URL above in the location bar of your browser. The value of this parameter is a unique token. Step two of the client-login process is to POST that token back to the API for confirmation. Upon success, the user is logged in, their browser gets cookies on api.wikitree.com with their session, and a result JSON object is returned with the user ID and WikiTree ID for the now logged-in user.

From the Query String, we found an authcode = <<authcode>>.

So next we POST that back to the API, again with action = clientLogin, for confirmation.

$.ajax({
	// The WikiTree API endpoint
	'url': API_URL,

	// We tell the browser to send any cookie credentials we might have (in case we authenticated).
	'xhrFields': { withCredentials: true },

	// Doesn't help. Not required from (dev|apps).wikitree.com and api.wikitree.com disallows cross-origin:*
	//'crossDomain': true,

	// We're POSTing the data so we don't worry about URL size limits and want JSON back.
	type: 'POST',
	dataType: 'json',
	data: { 'action':'clientLogin', 'authcode':authcode }
}).done(function(data) {
	if (data.clientLogin.result == 'Success') {
		// Copy the userName (WikiTree iD) and userId returned by the API
		// in our local cookies so we know in the future whether or not the
		// user is signed in.
		userName = data.clientLogin.username;
		userId = data.clientLogin.userid;
		$.cookie('userName', userName);
		$.cookie('userId', userId);

		// Show the user the JSON result of our post.
		$('#authcodeResult').html(FormatJSON(data));
		$('#confirmed').show();
	} else {
		alert("Login failure");
	}	
});
		

3. Authenticated!

The user is (already) authenticated and logged into the API. We've stored their user_id (<<user_id>>) and WikiTree ID (<<user_name>>) here (with cookies on the local hostname) so we know if they depart and return that they're logged in. We don't need to send any further authentication/identity information to the API. We just need to tell the browser to send along the cookie information for the API hostname so that the user's session information goes through and the API action is processed for the user signed in.

You can test this by using an API function like getProfile where you can now retrieve data for private profiles that are on your own watched list.

We can also check on our login, e.g. when the page loads, to make sure the userId we stored is (still) logged in over at the WikiTree API:

If you want to see the checkLogin verification fail, you can logout of the API. You'll return here where the locally stored Name/Id are still set. But checkLogin will fail so we know you aren't actually logged in at the API.