Frequently Asked Questions
We have a very simple API, but developers still have questions. Below are common questions and answers. If you don't find what you're looking for, ask on StackOverflow (and tag the question with
toopher), tweet the question, or email us.
What does this API error mean?
If you run into an API error, please ask about it publicly on StackOverflow. See Toopher API: What does the message "Not a valid OAuth signed request” mean? and Toopher API: What does the message “No pending pairing requests with specified pairing_phrase” mean?.
What is the Toopher two-step?
That is what we call the process of using Toopher: pairing and authenticating. Pairings are only useful when used in authentication requests, and authentication requests require a pairing ID, so the two are linked.
What is pairing?
Pairing is the process of linking a user's phone to your Toopher-enabled service. After pairing, a user's Toopher app will include an entry for your site or service. When making authentication requests, the user's pairing ID is used to properly route the request.
How does Toopher secure requests?
We use HTTPS and all requests are OAuth encoded while in flight.
What could people do with my Toopher credentials?
It is important to keep your credentials safe. If someone gets your secret, they can impersonate you and annoy users by issuing fake requests or worse.
We recommend the following practices:
- Harden your web server
- Use strong passwords
- Limit permissions
- Store the credentials in environment variables rather than in a file or database
- Enable Toopher on your account
I have the demo, now what?
Each language library also contains a demo. The demo is meant to help you understand Toopher--it is not a complete drop-in implementation. See the demo to real world guide.
What is the expected behavior of automation when location services on the mobile device are turned off?
For android devices the answer is simple: if location services are turned off, the user will be prompted. For iOS things are a bit more complicated (due to Apple's more stringent limitations to background application execution): if the user has location services turned on when (or soon after) they arrive in a location with automated responses, the API server will (for a limited amount of time) continue to automate responses for requests that match the automation criteria (requester, user, terminal & action). If location services remain off, the automation will eventually expire and prompt the user.
What is the expected behavior of the app when the mobile device is in airplane mode?
The app's functionality in airplane mode is very limited: you can generate OTPs for a pairing and that's about it.
What does it mean to automate and DENY a request?
The app will allow you to set up a request to be automatically denied. The use case for where an automatic deny is not something we typically encounter, but the app will nevertheless allow you to do it.
What is the maximum age of an OTP?
OTPs are valid for a period of 30 seconds.
When should an authentication request make the app open without user action?
Android will display an authentication request automatically assuming a data connection is available which does not block Google Cloud Messaging (GCM). On iOS, the user must activate a received Apple Push Notification Service (APNS) message to launch the app. On both platforms if the GCM/APNS does not reach the device, a user can also launch the app manually at which point it will display any pending authentication request.
If you lose a phone and recover the pairing, what is the state of the app on the lost phone?
When performing a recovery, the pairing associated with a lost phone is deactivated and the phone will no longer receive authentication requests associated with the pairing.
The account recovery page suggests you have specific ideas in mind for conducting account recovery and may be implementing a unifying two-factor management solution. Could you please fill us in?
Certainly - this is part of the long-term vision at Toopher where we plan to centralize account recovery for all our end-user's pairings through us as opposed to delegating this to each individual relying party. An example of this would be where we provide an alternative authentication method that can be used to lockdown all my accounts (lost phone) or transfer all of my strong authentication (new phone). Our planning here is a still at an early stage so a lot of this still remains to be designed and built, but it's on our roadmap for increasing our offering and lessening the burden on relying parties for implementing strong authentication.