Request Format & Authentication

Normal Request Authentication:

All requests must have the following post values to authorize the request:

  • key : Your account username.
  • secret : Your account API secret.
  • sig : This is an md5 hash of your gatekeeper concatenated with your request action.

For example, let's assume that your username is "joeuser", your secret is "secretsauce", and your gatekeeper is "keymaster" - and that you are trying to POST a request to the URL:
http://framesocket.com/api/media/query.php

You would include the following values to authorize your request:

  • key=joeuser
  • secret=secretsauce
  • sig=md5 hash of "keymasterquery"

For more information on generating MD5 hashes on mobile devices, please read below.

Obviously - you should protect your secret and gatekeeper. These should never be exposed in plain-text in any form that an end user could find them. For example - DO NOT use a form on your website that has the values simply within hidden input fields - unless you are quite certain that you have no malicious end users and that they will appreciate JSON output. The better option would be to use a single-use token.

Single Use Tokens

For some applications it makes more sense to request a single-use token that works for only one API request.

Generating a Single-Use Token:

To generate a new single-use token, you must submit an authorized request...

Request Action: generatetoken
Request URL: http://framesocket.com/api/auth/generatetoken.php

If successful, the request will return a JSON response similar to this:


{
	"success":1,
	"error":"",
	"warnings":"",
	"token":"abcdefghijklmnopqrstuvwxyz123456abcdefghijklmnopqrstuvwxyz123456"
}

You can then use the returned token to sign a SINGLE API request. That request must have the following:

  • key : Your account username.
  • token : This is your single use token.

For example, let's assume that your username is "joeuser", and your returned token was in the example above.

You would include the following values to authorize your request:

  • key=joeuser
  • token=abcdefghijklmnopqrstuvwxyz123456abcdefghijklmnopqrstuvwxyz123456

If you're using this for web-form uploads - please note that you can use a callback URL with the media upload action. For more information, click here.

Generating MD5 Hashes

Heads up! We know that it isn't easy to generate an md5 hash within the Android or iPhone SDK. Here are some code samples to help you get started.


Android

MD5 Helper Function. Copy this into your Activity that requires creating md5 hashes.


public static final String md5(final String input) {
	
	try {
		
		// Create MD5 Hash
		MessageDigest messageDigest = java.security.MessageDigest.getInstance("MD5");
		messageDigest.update(input.getBytes());
		byte messageDigestBytes[] = messageDigest.digest();
		
		// Create Hex String
		StringBuffer md5String = new StringBuffer();
		
		for (int i = 0; i < messageDigestBytes.length; i++) {
			
			// Convert to Hex
			String h = Integer.toHexString(0xFF & messageDigestBytes[i]);
			
			// Make sure we have leading zeros.
			while (h.length() < 2) {
				h = "0" + h;
			}
			
			// Append to our final String
			md5String.append(h);
			
		}
		
		// Return our MD5 Hash
		return md5String.toString();

	} catch (NoSuchAlgorithmException e) {
		
		// In case the device does not support MD5.
		e.printStackTrace();
		
	}
	
	return "";
	
}

Example Usage:


String hashMePlease = new String("inputstring");
String md5String = md5(hashMePlease);

iPhone / iOS

MD5 NSString Helper. Create the following files within your project:


//  md5.h

@interface NSString (md5)

+ (NSString *) md5:(NSString *)str;

@end

//  md5.m

#import <CommonCrypto/CommonDigest.h>
#import "md5.h"

@implementation NSString (md5)

+ (NSString *) md5:(NSString *)str {
	const char *cStr = [str UTF8String];
	unsigned char result[16];
	CC_MD5( cStr, strlen(cStr), result );
	
	NSString *returnString = [[[NSString alloc] initWithFormat:
								@"%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X",
								result[0], result[1], result[2], result[3], 
								result[4], result[5], result[6], result[7],
								result[8], result[9], result[10], result[11],
								result[12], result[13], result[14], result[15]
								] autorelease];
									
	return [returnString lowercaseString];
}

@end

Example Usage:


// Be sure to #import "md5.h"

NSString *hashMePlease = [[NSString alloc] initWithString:@"inputstring"];
NSString *md5String = [NSString md5:hashMePlease];
Have a question? We are currently: