POST authentication_request/initiate

Initiate an authentication request

Resource URL

https://api.toopher.com/v1/authentication_requests/initiate

PARAMETERS
pairing_id
required
The unique string identifier id returned by a previous pairing request.
terminal_name
semi-required
A human recognizable string which represents the terminal from which the user is making the request. This is displayed to the user on the mobile app when authenticating. If this is not included, then a terminal_id returned from a previous request must be provided (see below). These should be unique values for each different device from which a user connects to your service (as best you can detect).
terminal_id
semi-required
The unique string identifier generated and returned by the Toopher web service for a given terminal from a previous request. If this is not included, then a terminal_name is required (see above). If both are provided, the terminal_name for the given terminal_id will be updated. This allows Toopher to handle unique terminals independently of a terminal's name changing.
action
optional
A string describing the action being allowed or denied; for example, 'login'.
format
optional
Allows the response formatting to be specified. Valid values are: xml, json, and yaml. The default is json.
terminal_name_extra
optional
A string to help differentiate identically named terminals. It is strongly recommended that you use this parameter in addition to the terminal_name and that terminals with the same terminal_name have different terminal_name_extra values.
challenge_required
optional
Allows the requester to require that a user secure their Toopher app with a pattern lock. The user will be asked to input their pattern in order to authenticate. To enable, set this parameter to true. The default value is false.
automation_allowed
optional
Useful for disallowing automation. This may be useful for sensitive interactions that necessitate the user manually authenticating the request. To disable automation in safe locations, set this parameter to false. The default is true.
otp
optional
The IETF standard RFC6238 one-time-password, unique to each pairing, generated in the Toopher mobile app when the user clicks on a pairing. If submitted, the Toopher API will verify the OTP, and immediately return the authentication result (i.e. pending will be False, and granted will be True if the OTP is valid). This feature allows for fallback authentication in case the user's mobile device does not have network access.

Response

Upon success, a status object will be returned containing 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 authentication request. It can be used to request status information for the authentication request.
pending A boolean value indicating if the request is still pending.
granted A boolean value indicating if the request was granted..
automated A boolean value indicating if the request was automated.
reason A string which provides additional information about the reason for the authentication outcome (if available).
terminal A nested terminal object that will contain (among others) the following fields:
  • id: A unique string identifier generated and returned by the Toopher web service for a given terminal.
  • name: The human recognizable terminal name associated with the given id.
action A nested action object that will contain the following fields:
  • id: A unique string identifier generated and returned by the Toopher web service for a given action.
  • name: The description of what action the user is authorizing.

This request will return immediately to facilitate asynchronous operations.

Authentication 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 This is the base error, which may be raised for various reasons. Please see the internal error_message for additional details.
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.
404 - Not Found You may receive a 404 if an input item does not exist.
409 - Conflict You may receive a 409 if the input user or their pairing or terminal cannot be found, if a user has opted out of Toopher via SMS or by deleting the pairing in the Toopher mobile app.
429 - Too Many Requests You may receive a 429 if you exceed the rate limit for the input authentication request.

GET authentication_requests/{authentication_request_id}

Check the status of an authentication request

Resource URL

https://api.toopher.com/v1/authentication_requests/{authentication_request_id}

Response

Upon success, the body will contain the status of the pairing (as specified above) in the desired format. Note: An option to include a callback parameter to be notified of request completion will be available soon.

Authentication 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.
404 - Not Found You may receive a 404 if the input ID does not exist.

Next Up

Once you have authenticating & pairing setup, you will want to provide a way for users to recover their account if they lose their device.

Demo to Real World »