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.

Authentication

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=https://api.opentok.com/hl/session/create
headerstr="X-TB-PARTNER-AUTH: API_KEY:API_SECRET"
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.

Methods

Create Session

Generate a new session.

Resource URL:

https://api.opentok.com/hl/session/create

Resource verb:

POST

POST Parameters

location
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.
p2p.preference
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
Host: https://api.opentok.com/hl
X-TB-PARTNER-AUTH: api_key:partner_secret

location=10.1.200.30&p2p.preference=disabled

Sample Response

The response is XML data of the following form:

<sessions>
  <Session>
    <session_id>SESSION_ID</session_id>
    <partner_id>API_KEY</partner_id>
    <create_dt>DATE</create_dt>
    <session_status></session_status>
  </Session>
</sessions>

IRC Live Chat

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