POST pairings/create

Create a pairing

Resource URL

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

PARAMETERS
pairing_phrase
required
The pairing phrase generated by a user's mobile application.
user_name
semi-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_id
semi-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.
format
optional
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:

Pairing Response Example


Errors

Errors are possible. Errors will have an HTTP status code of 400 or greater; each response should have a JSON object with an error_code and error_message.

400 - Bad Request You may receive a 400 if we cannot understand the input to the pairing function.
401 - Unauthorized You may receive a 401 due to OAuth errors.
403 - Forbidden You may receive a 403 when accessing a resource that does not belong to you, attempting to use a Requester that was deleted, using a feature that is not allowed by your current plan.
409 - Conflict You may receive a 409 when attempting to pair via SMS with a user who has opted-out of receiving SMS from Toopher.

GET pairings/{pairing_id}

Check the status of a pairing

Resource URL

https://api.toopher.com/v1/pairings/{pairing_id}

Response

Upon success, the body will contain the status of the pairing (as specified above) in the desired format.

Pairing Status Response Example


Errors

Errors are possible. Errors will have an HTTP status code of 400 or greater; each response should have a JSON object with an error_code and error_message.

400 - Bad Request You may receive a 400 if we cannot understand the input to the pairing function.
401 - Unauthorized You may receive a 401 due to OAuth errors.
403 - Forbidden You may receive a 403 when accessing a resource that does not belong to you.

Next Up

Once you have a pairing, you can authenticate users.

Authenticating »