Documentation

Pairing

To pair a user's mobile app with your service you'll need a "pairing phrase". A pairing
phrase is a short phrase that can be generated by the Toopher mobile app. Prompt the user for the phrase
and make the following request:

POST pairings/create

Create a pairing

Resource URL

https://api.toopher.com/v1/pairings/create

PARAMETERS

pairing_phraserequired

The pairing phrase generated by a user's mobile application.

user_namesemi-required

A human recognizable string which represents the user making the request (usually their username).
This is displayed to the user on the mobile app when authenticating. If this is not included, then a
user_id returned from a previous request must be provided (see below).

user_idsemi-required

The unique string identifier generated and returned by the Toopher web service for a given user from a
previous request. If this is not included, then a user_name is required (see above). If both are
provided, the user_name for the given user_id will be updated. This allows Toopher to handle unique
users independently of a user's name changing.

formatoptional

Allows the response formatting to be specified. Valid values are: xml, json, and yaml. The default is
json.

Response

Upon success, a status object will be returned with the following fields formatted as desired.

id

A unique string identifier generated and returned by the Toopher web service that is used to
identify this pairing. It can be used to request status information for the pairing and must be
included in subsequent authentication requests for this user.

user

A nested user object that will contain the following fields:

id: A unique string identifier generated and returned by the Toopher web service for a given
user.

name: The human recognizable user name associated with the given id.

pending

A boolean value indicating if the request is still pending.

enabled

A boolean value indicating whether or not the pairing has been acknowledged and enabled by the
user.

Upon creating a pairing, the user will be notified and can choose to grant or deny the pairing. The user
must grant the pairing before authentication requests will be successful. The status of a pairing can be
checked with the following request: