Connection Token Creation

In order to authenticate a user connecting to a OpenTok session, a user's page must pass an authentication token along with the API key. Tokbox provides the developer with an API key when they sign up for the OpenTok API. To generate an authentication token, you connect with the TokBox server, passing the session ID for the session the user will connect to:

When you are testing your application, you can simply use 'devtoken' or 'moderator_token' test token strings. (The 'moderator_token' string was added in OpenTok v0.91.5.) The 'devtoken' test token string puts the user in the role of a publisher (which restricts the user using the force unpublish and force disconnect moderation features). The 'moderator_token' test token string puts the user in the role of a moderator (allowing them full permissions to use all of the OpenTok API). However, in production, you must use a token created using the OpenTok server-side libraries.

The following PHP code example shows how to obtain a token using the OpenTok PHP server-side library:

<?PHP

require_once 'OpenTokSDK.php';

$a = new OpenTokSDK(API_Config::API_KEY,API_Config::API_SECRET);
print $a->generate_token('your_session_ID'); // Replace with the correct session ID
print "\n";

Calling the generate_token() method returns a string. This string is the token. You use server-side PHP code to include the token in the served web page.

Although the example illustrates use of the OpenTok PHP libary, the other OpenTok server-side libraries (for Java, Python, and Ruby) work in much the same way. In each, you generate a token by calling the generate_token() method of the OpenTokSDK object. The method takes three arguments:

• session_id (String) — The session ID corresponding to the session to which the user will connect.
• role (String) — Optional. Added in OpenTok v0.91.5. This defines the role the user will have. There are three roles: subscriber, publisher, and moderator. Subscribers can only subscribe to streams in the session (they cannot publish). Publishers can subscribe and publish streams to the session, and they can use the signaling API. Moderators have the privileges of publishers and, in addition, they can also force other users to disconnect from the session or to cease publishing. The default role (if no value is passed) is publisher.
• connection_data (String) — Optional. A string containing metadata describing the connection. For example, you can pass the user ID, name, or other data describing the connection. You may obtain this data from a server-side database or from data provided to you by the client, depending on your application.
• expire_time (int) — Optional. The time when the token will expire, defined as an integer value for a Unix timestamp (in seconds). If you do not specify this value, tokens expire in 24 hours after being created. The expire_time value, if specified, must be within seven days of the creation time.

Important: To obtain a session ID for production, change the API_URL constant (in the server-side library) to "https://api.opentok.com/hl".

Before you launch your site, you can use the the staging environment without generating authentication tokens:

• As mentioned before, while using the test sandbox, you can use the generic string "devtoken" or "moderator_token" in place of a proper server-generated token. (You can also use a server-generated token. You will receive errors if the token is invalid for the session.)
• Load the OpenTok JavaScript library from the following URL:

<script src="http://staging.tokbox.com/v0.91/js/TB.min.js"></script>

Use the test sandbox (staging) environment for testing only. The OpenTok staging server is not intended for production environments.

When you launch your site, you will need to switch to the production server:

• Register your app with Tokbox. See the Launch page
• Use the OpenTokSDK.generate_token() method to obtain a unique token string for each user.
• Load the OpenTok JavaScript library from the following URL:

<script src="http://static.opentok.com/v0.91/js/TB.min.js"></script>

For more details, see the OpenTok server-side libraries documentation.

Next workflow step: Initialize and connect to a session.