There are two main methods of authenticating your app. The first, an OAuth-like process, is required for webapps. The second is only available to mobile and desktop apps where, due to device restrictions, the regular method cannot be used.
Authenticating your app to the user
Before your application can use our API calls to pull data or images on behalf of a Shoeboxed user, the user must explicitly authorize your application.
To authenticate, send your user with the following POST parameters to the API endpoint.
|appname||The name of your application. (Provided by us.)|
|appurl||The URL (on your domain) to redirect the user to after they have authenticated your app.|
|appparams||A string of parameters to echo back to your application after the authentication and redirect to appurl. Cannot be null.|
|SignIn||This parameter must be set to “1″ to initiate the authentication|
If the above parameters are correct, the user will be directed to a screen where the user can enter their username and password to authenticate your app. If there is an error, the user will be redirected to http://www.shoeboxed.com.
After a successful authentication, the user will be redirected to your appurl (on your domain) with parameters set by Shoeboxed. The URL will take the following form:
|token||A token specific to a user that proves this user has authenticated your application. You will use this to authenticate subsequent API calls (see SbxUserToken below). The token’s does not expire; however, the user has the ability to revoke tokens, so your application may have to re-authenticate the user on subsequent visits. You can see if a token has expired by attempting an API method call and checking to make sure it does not return an authentication error.|
|uname||The user’s Shoeboxed username.|
Authenticating API calls
With each API call, you must include as part of RequesterCredentials the API user token (specific to your API app) and the Shoeboxed user token (obtained with the process above).
|ApiUserName||This is the name of your API app, specified by you when you signed up for API access. Used for API calls that do not apply to one specific user (for example, calls that have to do with user registration).|
|ApiUserToken||Unique identifier of your API app, given to you when you signed up for API access.|
|SbxUserToken||This token, given during the user authentication process (see above), proves that the user has given permission for your API app to access his or her data.|
Mobile and desktop authentication
For mobile and desktop applications where the regular authentication process is not feasible due to device limitations, Shoestrings offers an alternative: the GetLoginCall. Simply put, it authenticates a Shoeboxed user with a username and password, and returns a SbxUserToken that can be used to authenticate subsequent calls. Please refer to the documentation for more details.
However, for security reasons, this method is restricted; please contact us to demonstrate your need.