Send tokens to Apideo

This document describes how you can send tokens to Apideo. If you are not confortable with the notion of token-based security, you should start by reading the "Token-based security principles".

The passphrase mechanism

You can send tokens by encoding them in a XML message.

The XML message is sent to Apideo via a simple HTTP POST message. However, Apideo needs to know that you are the legitimate owner of the account you submit a token to. We do this by sharing a common secret: a passphrase.

You will need to generate a passphrase for your account. To do this connect to your Apideo account, then go to Subscriptions > Configure security settings > Access the token-based security configuration screen.

By clicking the Regenerate passphrase button, you will generate a passphrase you can use.

Performing the call

The call to Apideo is performed using a PHP POST request. You will perform the POST to this URL:

http://security.apideo.com:5080/apideo_room2/securitytoken.do

You will pass 2 parameters:

xmltoken: Your XML message containing the tokens
securityphrase: The passphrase for your account

The HTTP call will return an empty string (nothing) if everything goes right. If an error occurs, a XML message will be returned.

Debugging your calls

In order to understand what is happening inside the Apideo servers, you can view the list of declared tokens using the token-based security configuration screen. This view is very efficient to understand what is stored inside Apideo, and therefore why an access is allowed or denied.

Below is a sample representation of a token 'ABCDE' in your admin console:

A sample PHP application

Let's have a look at a sample PHP application that creates a token and sends that token:

<?php 
/**
 * This sample sets a token that forces a userprofile 
 * where the attribute manager must be true.
 * The Curl library is used to send the HTTP message to Apideo.
 */
 
// The token we create:
// Do not forget to replace the Apideo key with your Apideo key when testing.
$xml = '<?xml version="1.0" encoding="utf-8"?>
<account xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	xsi:noNamespaceSchemaLocation="http://www.apideo.com/api/security/security-token.xsd"
	apideoKey="0D851CAEDA56DDC8A3">
	<token name="A45R8GF6fsd4ze4c5se" ttl="86400">
		<defaultRoom access="reject">
 
		</defaultRoom>
		<room access="allow" name="myroom">
			<userlist access="allow" filter="obj.manager == true" />
			<userprofile access="allow" 
				filter="obj.manager == true &amp;&amp; obj.value &gt; 12" />
 
			<sendEvents defaultAccess="reject">
				<sendEvent access="allow" category="chat" />
				<sendEvent  access="allow" category="joinChat" />
			</sendEvents>
			<startCameras defaultAccess="reject">
				<startCamera access="allow" name="mystream_12" />
			</startCameras>
			<viewStreams defaultAccess="reject">
				<viewStream access="allow" regex="/mystream_[0-9]*/" />
			</viewStreams>
		</room>
	</token>
</account>';
 
// The security phrase must be generated in your admin console and pasted below.
$params = array(
	"securityphrase"=>urlencode("4D920BD734F77856DD7AE46F14135D020896D49E90DD47196FFF"), 
	"xmltoken"=>urlencode($xml)
);
$fields_string = "";
foreach($params as $key=>$value) { $fields_string  .= $key.'='.$value.'&'; }
rtrim($fields_string,'&');
 
// preparation de l'envoi
$ch = curl_init();
 
curl_setopt( $ch, CURLOPT_URL, "http://security.apideo.com:5080/apideo_room2/securitytoken.do");
 
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, TRUE );
curl_setopt( $ch, CURLOPT_POST, TRUE );
curl_setopt( $ch, CURLOPT_POSTFIELDS, $fields_string );
 
if( curl_error($ch) ) { 
	throw new Exception("An error occured while sending request to Apideo. Error code: ".curl_error($ch));
} else {
	$response = curl_exec( $ch );
}
curl_close( $ch );
 
if ($response != "") {
	throw new Exception("An error occured while sending request to Apideo:<br/>".htmlentities($response));
}
 
?>		
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
	<title>Join room token test</title>
 
	<script type="text/javascript" src="/apideo/apideo.js"></script>
    <script>
	Apideo.defaultUrl = "localhost"
 
	function init() {
		conn = Apideo.connect("0D851CAEDA56DDC8A3");
		// We join the room, passing in parameter the correct user profile and the token.
		room = conn.joinRoom("myroom", {manager:true, value:13}, "A45R8GF6fsd4ze4c5se");
		room.onSecurityError(function(category, type, msg) {
			// The security error will not be triggered. No alert should be displayed.
			alert("Security alert: "+category+" "+type+" "+msg);
		});
		room.onLoad(function() {
			alert("Success. The room has been joined.");
		});
	}
 
 
   </script>
</head>
 
 
<body onload="init()">
Testing access with tokens and userprofile with filter set.
An alert should pop on this page saying that the room has correctly been joined.
</body>
</html>