OpenTok REST API reference

The OpenTok REST API is used by developers to generate sessions. Our server SDKs wrap our REST API to make calls to our platform easier to make.


REST API calls must be authenticated using a custom HTTP header: X-TB-PARTNER-AUTH. Send your API key and partner secret concatenated with a colon:

X-TB-PARTNER-AUTH: <api_key>:<partner_secret>

To call the function from the command line, you could issue a command like the following:

export TB_url=
curl -X POST -H "$headerstr" $TB_url

Replace the API_KEY and API_SECRET with the API key and partner secret provided to you in your OpenTok dashboard.


Create Session

Generate a new session.

Resource URL:

Resource verb:


POST Parameters

The location setting is optional, and generally you should not include it. This setting is an IP address that TokBox will use to situate the session in its global network. If no location hint is passed in (which is recommended), the session uses a media server based on the location of the first client connecting to the session. Pass a location hint in only if you know the general geographic region (and a representative IP address) and you think the first client connecting may not be in that region. If you need to specify an IP address, replace IP_ADDRESS with an IP address that is representative of the geographical location for the session.
Enter "enabled" if you prefer calls to be connected via a peer-to-peer connection, and "disabled" for multiparty calls. (optional, default: disabled)

Sample Request

POST /session/create HTTP/1.1
X-TB-PARTNER-AUTH: api_key:partner_secret


Sample Response

The response is XML data of the following form:


IRC Live Chat

Have a quick question? Chat with TokBox Support on IRC. Join chat