Skip to main content
REST API - Tokens - Overview
A Token is a resource that allows developers to build public applications that authorizes certain API requests on behalf of a User.  An unlimited number of users in guest mode are able to interact with token-authenticated applications.

For example, Tokens let developers build a widget on behalf of a user that will allow customers to call that user through a web page. For example, a pizza parlor as part of a special promotion may want to enable users to make calls from a predefined number on their website that will connect web users directly to the pizza parlor. By enabling the token to allow concurrent (more than one) interaction with the application, multiple users could call at the same time.

Currently, YouPhone tokens are for Flash applications only. After you create the token using REST by specifying the token type "uPhone", you can use the token in a Flash application by providing the token as a login credential.

REST API - Tokens - Methods
NameResource
Response
Notes
GET
/tokens/<guid>
(200) Tokens owned by <guid>  
Get all Tokens
POST           
/tokens (201) Location of new Token Create new Token
GET
/tokens/<guid>/<tokenId>   
(200) Single Token Details
Retrieves details for a single Token.
DELETE
/tokens/<guid>/<tokenId>    
(204) Delete Token
Deletes the specified Token.
REST API - Tokens - Properties
Name
Methods
Value
Notes
idGET string
(req) The ID for this Token.
typeGET, POST uPhone (req) Only "uPhone" is currently supported.
descriptionGET, POST <devId>
(req) A description of this Token.
callerGET, POST <devId>
Number or address to use as caller ID.This is the source number for the Token, which can be a Purpose Number assigned to the user. This number will appear as the Caller ID when the user's number is called through a token-enabled Application.
calleeGET, POST <devId>
(req) Number or address to call. This is the number that will ring when a call is made from the token-enabled Application.
maxConcurrent GET, POST       
int           
Maximum number of concurrent connections using this Token. For example a widget could be placed on a website enabling users to call in directly to a particular pizza parlor. The widget could be set to only allow 12 concurrent calls, meaning only 12 users can call the pizza parlor via the widget at any particular time.
startDateGET, POST date (opt) The date and UTC timestamp before which, the Token is invalid. For example the date a promotion would start. Valid date format is YYYY-MM-DD:THH:MM:SSz. Coordinated Universal Time (UTC) is a time standard based on International Atomic Time (IAT) with leap seconds added at irregular intervals to compensate for the Earth's slowing rotation. Leap seconds are used to allow UTC to closely track UT1, which is mean solar time at the Royal Observatory, Greenwich. The format is in dateTime as described by XML Schema: http://www.w3.org/TR/xmlschema-2/#dateTime. "Z" is the timezone and denotes UTC, however it is possible to have "-800" to denote PST.
endDateGET, POST
date (opt) The date and UTC Timestamp after which, the Token is invalid. For example the date a promotion would end. Valid date and timestamp format is YYYY-MM-DD:THH:MM:SSz. The"Z" at the end of a timestamp denotes the timezone.
digestGET POST digest Encrypted digest to use. This authorizes anonymous calls to the YouPhone token and must be complied into the Application.
REST API - Tokens - Examples

Creating a YouPhone Token

To create a new YouPhone token, the callee and type (uPhone) must be posted to a Users token collection - as identified by the GUID. Users must be authenticated before tokens can be created and they can only be created in the collection corresponding to this authenticated user. The additional parameters for setting caller ID, start and end dates, and the maximum number of concurrent calls permissible with the token may also be set at the time of creation. 

	
<< GET /rest/1.0/tokens/9764e31d-65bf-4b2a-a3f1-8b0cdad6e8d6/123


{
   "type":"uPhone",
   "callee":"18005551212",
   "caller":"18008675309",
   "description":"Token 1",
   "startDate":"2010-01-04T08:00:00Z",
   "endDate":"2010-01-05T08:00:00Z",
   "maxConcurrent":12
}

Retrieve Token Details

Once a token is generated the details can be retrieved by a GET against the resource LOCATION.

	
<< GET /rest/1.0/tokens/9764e31d-65bf-4b2a-a3f1-8b0cdad6e8d6/123


{
   "entry":{
      "type":"uphone",
      "id":123,
      "description":"Token 1",
      "callee":"18005551212",
      "caller":"18008675309",
      "maxConcurrent":12,
      "startDate":"2009-07-09T00:00:01Z",
      "endDate":"2009-08-09T23:59:59Z",
      "digest":"MX6eN74Jpv5+sWprEUQjnjp7"
   }
}

Retrieving all Tokens

GET /rest/1.0/tokens/ can be used to retrieve all tokens for the specified GUID. In the example below three tokens were returned.

	
<< GET /rest/1.0/tokens/9764e31d-65bf-4b2a-a3f1-8b0cdad6e8d6


>> 200 OK
{
   "entry":[
      {
         "type":"uphone",
         "id":123,
         "description":"Token 1",
         "callee":"18005551212",
         "caller":"18008675309",
         "maxConcurrent":12,
         "startDate":"2009-07-09T00:00:01Z",
         "endDate":"2009-08-09T23:59:59Z",
         "digest":"MX6eN74Jpv5+sWprEUQjnjp7"
      },
      {
         "type":"uphone",
         "id":124,
         "description":"Token 2",
         "callee":"18005551213",
         "caller":"18008675309",
         "maxConcurrent":12,
         "startDate":"2009-09-24T00:00:01Z",
         "endDate":"2010-09-24T23:59:59Z",
         "digest":"9fO5BSxNcgdgo4oJZM="
      }
   ]
}