API Reference: OAuth Authentication

There are two ways to authenticate to Solve when using the API – using a token-based method or OAuth. If you’re building an application for many other people to use (e.g. iPhone/Android App or integration with another SaaS service), we recommend using OAuth, otherwise for things like into your organization’s software, it’s easiest to use the token-based method.

How to register your OAuth application

Solve limits access to the OAuth service. Only pre-approved applications are permitted to use the Solve OAuth service.

Send a request with the name of your application and a detailed description of what it is. Our team will review it quickly and if your application for OAuth access is approved, we will send you an assigned OAuth consumer key and OAuth consumer secret.

The OAuth authorization process

The OAuth authorization process involves a series of interactions between your application, Solve’s OAuth service, and the end user. At a basic level, the process is as follows:

  1. Your application requests access and gets an unauthorized request token from Solve’s OAuth service
  2. Solve asks the user to grant you access to the required data
  3. Your application receives an authorized request token from the OAuth service
  4. You exchange the authorized request token for an access token
  5. You use the access token to request data from Solve’s API

Your application must sign each OAuth request it makes. You must use a HMAC-SHA1 signature to sign your requests. Solve does not set limits on the access it allows through the Solve APIs. However, you must specify scope value on getting unauthorized request token - for Solve API scope value is “api”.

If the user approves your application’s access request, Solve issues an authorized request token. Only an authorized request token can be exchanged for an access token, and this exchange can be done only once per authorized request token.

By default, access tokens are long-lived. Each access token is specific to the user account specified in the original request for authorization, and grants access only to the Solve API. Your application should store the access token securely, because it’s required for all access to a user’s data.

Setting up a mechanism to manage OAuth tokens

When you obtain an OAuth access token for a user’s data, you must use that access token for all future interactions with the Solve API on behalf of the user.

Your application must manage token storage securely. You should obtain not more than one access token per user.

If your application supports multiple user accounts, you must keep track of which account each token is associated with. Each OAuth token is specific to the user who authorized access. Your application must be able to associate a token with the correct user.

Each request to the Solve API must be signed, and must include a valid OAuth access token. In general, each request is made in the form of a HTTP GET request, with the access token and signature included in the header. Requests that write new data should use HTTP POST/PUT, and requests that delete existing data should use HTTP DELETE.

Working with OAuth tokens

To use OAuth, your application must generate well-formed, signed token request calls, and handle the responses, for the following sequence:

  1. Get an unauthorized request token (via https://secure.solve360.com/oauth/request request)
  2. Authorize the request token (via https://secure.solve360.com/oauth/authorize request)
  3. Exchange the authorized request token for an access token (via https://secure.solve360.com/oauth/access request)

All OAuth requests must be signed with oauth_consumer_secret hash (generated for your application by Solve) using HMAC-SHA1 method. Be careful not to send oauth_consumer_secret hash to the Solve OAuth service.

Setting a callback URL

You can specify a value for oauth_callback in an https://secure.solve360.com/oauth/request request, to determine where Solve redirects the user after they authorize your access request. The callback URL can include query parameters. The redirect will include the same query parameters, as well as the authorized request token, which your application must be able to parse.

For mobile applications the value for oauth_callback parameter must be “oob”. Solve will direct the user to a web page that displays a verification number, after authorizing your access request. The user must manually return to your application and enter the verification number before you can obtain an authorized request token.

Setting scope

You must specify a value for oauth_scope in an https://secure.solve360.com/oauth/request request and the value obligatory must be “api” (case-sensitive).

Supported OAuth versions

Solve currently supports OAuth 1.0a.