Mobile Application Authorization Flow

Mobile authentication/authorization flow is very similar to the client-side flow, but it has a slightly different mechanism for handling the response data. This document provides details no how to integrate Geni into an iPhone application. Android and other mobile devices will work in a similar fashion.

Authentication & Authorization

To enter the authentication/authorization mobile flow, launch a browser from your mobile application and pass the following parameters to the authorization url:

Oauth URL

https://www.geni.com/platform/oauth/authorize

Parameters

Name Description Required
client_id Application key generated during the app registration. true
redirect_uri URL that the user's browser will be redirected back to once app authorization is completed. You can specify a custom URL that will be recognized by your mobile device, which launch your application. true
response_type For the mobile flow the response type should be set to "token". true
display For the mobile flow the display parameter should be set to "mobile". true
scope A comma delimited list of permissions that the application needs. By default the scope is set to a full data access. This is subject to change in the upcoming releases. false

Example

https://www.geni.com/platform/oauth/authorize?client_id=YOUR_APP_ID&redirect_uri=YOUR_APP_URL&response_type=token&display=mobile

By setting the display parameter to "mobile", you ensure that the login and the authorization screens will use a mobile layout. The client_id parameter can be either your application key or your application id. Application ids are shorter and can be used as registered urls of your mobile application.

Configuring iOS Callback

To register a callback to your iOS application, you must open your application's properties file and configure a custom url:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	...
  <key>CFBundleURLTypes</key>
  <array>
    <dict>
      <key>CFBundleTypeRole</key>
      <string>Editor</string>
      <key>CFBundleURLName</key>
      <string></string>
      <key>CFBundleURLSchemes</key>
      <array>
        <string>YOUR_APP_ID</string>
      </array>
    </dict>
  </array>
	...
</dict>
</plist>

You now can provide a redirect URL that will identify your application. See the following example:

Example

NSString *geniOauthBaseURL = @"https://www.geni.com/platform/oauth/authorize";

NSString *yourAppURL = [NSString stringWithFormat: @"%@/authorize", YOUR_APP_ID];

NSString *geniOauthURL = [NSString stringWithFormat:@"%@?client_id=%@&redirect_uri=%@&response_type=token&display=mobile", 
                                                    geniOauthBaseURL, YOUR_APP_ID, yourAppURL];
                         
[[UIApplication sharedApplication] openURL:[NSURL URLWithString:geniOauthURL]];

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:

Handling iOS Application Callback

To handle iOS application callback, add the following code to your iOS application delegate:

- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *) url {
	NSLog(@"Did come back from other application");
	
	// If the URL's structure doesn't match the structure used for Geni authorization, abort.
	if (![[url absoluteString] hasPrefix:[NSString stringWithFormat:@"%@://authorize", YOUR_APP_ID]]) {
	    return NO;
	}
	
	NSString *query = [url fragment];
	if (!query) {
	    query = [url query];
	}
	
	// parse parameters
	NSArray *pairs = [query componentsSeparatedByString:@"&"];
	NSMutableDictionary *params = [[[NSMutableDictionary alloc] init] autorelease];
	for (NSString *pair in pairs) {
	  NSArray *kv = [pair componentsSeparatedByString:@"="];
	  NSString *val = [[kv objectAtIndex:1]
	       stringByReplacingPercentEscapesUsingEncoding:NSUTF8StringEncoding];
	      
	  [params setObject:val forKey:[kv objectAtIndex:0]];
	}
	
	// get access token
	NSString *accessToken = [params valueForKey:@"access_token"];
	
	// If the URL doesn't contain the access token, an error has occurred.
	if (!accessToken) {  // handle error
      
	  return YES;
	}
	
	// store access token
	
	return YES;
}

Returned Fields

Name Type Description
status String If user cancels the authorization flow, the status will be set to "unauthorized".
message String Error message

Example

YOUR_APP_ID://authorize?status=unauthorized&message=user+canceled

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

Returned Fields

Name Type Description
access_token String Access token to be used with every API request
expires_in Number Seconds until the token will expire

Example

YOUR_APP_ID://authorize?access_token=ACCESS_TOKEN_GENERATED_BY_SERVER&expires_in=SECONDS_UNTIL_IT_IS_EXPIRED

Geni iOS Client SDK

Geni comes with a full featured iOS library that allows you to build dynamic iOS applications using the site data. It supports authentication, autherization and API calls to get the site data.

app001