FAQ

Frequently asked questions

How do I use theHub API?

theHub API was designed to be uniquely intuitive and simple. You should be able to go from "walk"to "run" rather quickly. However, here are some things that you might want to know that might speed you along:
‍

theHub API is a REST API
It only uses three of the HTTP verbs: POST, GET, and DELETE. (Updates to data are done via POST).
Every API entry in the API documentation (link sent upon signup) has a helpful curl example at the bottom.
With very few exceptions, you must first be logged-in before theHub will allow you to complete an API call. To let theHub know you are authenticated, theHub gives you cookies on login that you must pass with each subsequent API request.
Log in and obtain those cookies by calling POST /sessions (Access service).
On any of your API requests, if theHub successfully fulfilled it, you will receive an HTTP 200, with JSON in the body of the response.
If theHub received but was unable to fulfill your request you will receive an HTTP 403, with a 'success_code', and 'success_text' in the body of the response. theHub can return any of thousands of unique, integer success codes and descriptions. The integer, and its specificity, will make it easier for you to identify specific, blocking conditions, and respond as you see fit.

After signup I received an OTP (one-time password). What do I do with it?

Make two calls to POST /sessions. The first will give you a code, that you will use in the second as follows:
‍

Use POST /sessions to log in with your email address and the OTP you received by email.
You'll get success_code=8303 ("new password challenge - must supply new password; on attempt to log in").
Grab the value for 'success_token' in the response. We'll call it a temporary "session token".
Log in again with POST /sessions, but this time also pass the session token as 'session', and a new password as 'new_password'. Example:
{
   "login_id":"nobody@gmail.com",
   "password":"jfs5680!#",
   "new_password":"mynewpassword98!",
"session":"AYABeBCMCV73_GN9muCHmWYtOkwAHQABAAdTZXJ2aWNlABBDb2duaXRvVXNlclBvb2xzAAEAB2F3cy1rbXMAS2Fybjphd3M6a21zOnVzLWVhc3QtMjo0MTc1Njc5MDM0Njk6a2V5LzVjZDI0ZDRjLWVjNWItNGU4Ny05MASDFKW95ODdkOTZmY2RkMgC4AQIBAHjMzYCUO_8q5C8A2ROiB766gfjpnQnE4J7TTy8k2L86bAFGvzhcLjBvbNV4UV0li0fvAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMX6AF-LBC3WCdrxYjAgEQgDu90XApRX4ZtXkea9cvmqIM_JKTJdKjeyW_oR9eosF2Mm_RLGjyk4KYvxE5JiovfeqKxJ6bWtKG83fMeAIAAAAADAAAEAAAAAAAAAAAAAAAAACLqmYLVSyIzOaRatImWNZC_____wAAAAEAAAAAAAAAAAAAAAEAAADjyd0ZKeKDSMEVoAbxv2X8KCwk-v32b0Aty6xT348JsZTcQDZn6DllBE--XfVWEXo0TyBVkQBokmARrdmvcjuTiglCvaqYQk9SbkMpShGLY0z_M9sjz9LqorMMaqR2Ty_bbgWDvmt33kCq1HCD0McOhrCH1lIz5tR7M_Q-Jqz32TVxmgdtuK7Uzk4GVh07bFMon1UC11reqVVmohLiEuaUnjtCcrj5oeluU8dIVh4GEvdAgQXmfxS5HzS7SLnv4NQd3EQCMVM6cSxlzNRQFLDmZvwg9h7nWefX0Kk1qA_rZrjMFyr5ZHwnY0EfP4GJAXjUQ7h2"
}
That's it! Now you can log in with your new password.
Remember to save cookies obtained at login, and pass them with each subsequent call.

The OTP you receive on signup expires if you don't successfully change it within 24 hours from when it was issued. If this happens to you, contact us, and we'll issue you a new OTP.

What do I do if my OTP (one-time password) expired?

The OTP you receive on signup expires if you don't successfully change it within 24 hours from the time it was issued. If this happens to you,
‍

Use POST /users/<loginID>/password/resend, where '<loginID>' is the email address you used to sign up, to receive an updated code and restart the 24-hour timer. See documentation with example here (where "myinstance" is the name of your instance): https://myinstance.thehub.systems/docs/access/#/users/loginID/password/resendPOST
Use POST /sessions to log in with your email address and the password you just received by email. See documentation with example here (where "myinstance" is the name of your instance): https://myinstance.thehub.systems/docs/access/#/sessionsPOST
You'll get success_code=8303 ("new password challenge - must supply new password; on attempt to log in").
You'll also get an email with a verification code.
Log in again with POST /sessions, but this time also pass the verification code and a new password. Using the following example, replace param values with your own, where 'password' is the OTP received in the email, and 'session' is the verificaion code:
{
   "login_id":"nobody@gmail.com",
   "password":"jfs5680!#",
   "new_password":"mynewpassword",    "session":"906129"
}
That's it! Now you can log in with your new password.
Remember to save cookies obtained at login, and pass them with each subsequent call.

How does theHub API do error handling?

If theHub received, and was able to fulfill, a request the caller will receive an HTTP 200.
‍
If theHub received, but was unable to fulfill, a request the caller will always receive an HTTP 403, and in the body of the response, a JSON object that will contain attributes 'success_code' and 'success_text' that specifically describe the blocking condition, as in the following example:

{
   "success_code": 5003,
   "success_text": "no such requirement with requirement_id=123506 on attempt to get work efforts",
   "verb": "GET"
}

There are thousands of unique success codes that can be returned by theHub. This fine granularity, combined with the fact that they are always an integer value, makes it easier for callers to respond properly to specific conditions.

Get started
with theHub