User authentication and application authorization are handled as a two step process by redirecting the user to the login screen, followed by the authorization screen.

Authentication & Authorization

To enter the authentication/authorization flow, you must pass the following parameters to the authorization URL:

Oauth URL

Parameters

Example

If the user is already logged in, we validate the login cookie that we have stored on the user's browser and authenticate the user. If the user is not logged in, they are prompted to enter their credentials:

Once we have successfully authenticated the user, we will prompt the user to authorize your application:

If the user presses Don't Allow, your app is not authorized. The user will be redirected (via HTTP 302) to the URL you passed in the redirect_uri parameter with the following error information:

Returned Fields

Example

If the user presses Allow, your app is authorized. The user will be redirected (via HTTP 302) to the URL you passed in the redirect_uri parameter with an authorization code:

Returned Fields

Example

With this code in hand, you can proceed to the next step, app authentication, to gain the access token you need to make API calls.

Application Authorization

In order to authenticate your app, you must pass the following parameter to the request_token endpoint:

Oauth Endpoint

Parameters

Example

If your app is successfully authenticated and the authorization code from the user is valid, the authorization server will return the access token in a JSON format:

Returned Fields

Example

If your app failed to provide appropriate parameters, you will get one of the errors below in JSON format:

Returned Fields

Examples

Full Example in PHP

The following example demonstrates an authentication/autherization flow in a single PHP page.The example uses CSRF protection for extra security.

<?php 

   $app_id = "YOUR_APP_KEY";
   $app_secret = "YOUR_APP_SECRET";
   $my_url = "YOUR_URL";

   session_start();
   $access_code = $_REQUEST["code"];

   if (empty($access_code)) {
     $_SESSION['state'] = md5(uniqid(rand(), TRUE)); // CSRF protection
		 
     $geni_oauth_url = "http://www.facebook.com/dialog/oauth?client_id=" . $app_id 
		                   . "&redirect_uri=" . urlencode($my_url) . "&state=" . $_SESSION['state'];
											 
     echo("<script> top.location.href='" . $geni_oauth_url . "'</script>");
   }

   if ($_REQUEST['state'] == $_SESSION['state']) {
     $token_url = "https://www.geni.com/oauth/request_token?client_id=" . $app_id . "&client_secret=" . $app_secret
           			 . "&redirect_uri=" . urlencode($my_url) . "&code=" . $access_code;

     $params = json_decode(file_get_contents($token_url), true);

     $geni_api_url = "https://www.geni.com/api/profile?access_token=" . $params['access_token'];

     $profile = json_decode(file_get_contents($geni_api_url));
		 
     echo("Hello " . $profile->name);
   } else {
	 
     echo("Error: CSRF validation failed. Someone is attacking your site!");
   }
?>

Refreshing Access Token

If your access token has expired and you have a refresh token, you can get a new access token for the same scope by calling the oauth endpoint:

Oauth Endpoint

Parameters

Example

Returned Fields

Example