finsit API - OAuth

A collection of help pages for using the API.

OAuth

OAuth gives the users ability to a allow an external clientsoftware to access to our API without having to share their username and password to the external party. The current version of our API supports 3-legged OAuth and the addition OAuth client_auth.

You will need to register your application with us before you can use OAuth for authentication. Contact us and we will help you with the registration and you will receive an id and a key (OAuth consumer key and consumer secret) that will be used in the process of authentication.

OAuth resources

Please refer to the official documentation of OAuth 1.0 for complete specifications. You can use that specification for your own implementation. Although, the easiest way is to use an existing library.

OAuth resources on the Internet

OAuth client libraries

3-legged OAuth

The following flow in the diagram below can differ a little bit depending on the application. Although, normally this flow should be true for 3-legged OAuth.

Step 1: Request a token

URL https://web.foretagsplatsen.se/OAuth/RequestToken/
Supported verbs POST
OAuth http://oauth.net/core/1.0a/#auth_step1

The first step is to request a token; it is a prerequisite to the next step. The request for a token tells which application that is requesting (oauth_consumer_key & oauth_signature) and to which URL (oauth_callback) the user shall be redirected to in step 2. 

POST https://web.foretagsplatsen.se/OAuth/RequestToken/
OAuth oauth_nonce="QP70eNmVz8jvdPevU3oJD2AfF7R7odC2XJcn4XlZJqk", oauth_callback="http%3A%2F%2Flocalhost%3A3005%2Fthe_dance%2Fprocess_callback%3Fservice_provider_id%3D11", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1272323042", oauth_consumer_key="GDdmIQH6jhtmLUypg82g", oauth_signature="8wUi7m5HFQy76nowoCThusfgB%2BQ%3D", oauth_version="1.0"

An answer can look something like this

oauth_token=8ldIZyxQeVrFZXFOZH5tAwj6vzJYuLQpl0WUEYtWc&oauth_token_secret=x6qpRnlEmW9JbQn4PQVVeVG8ZLPEx6A0TOebgwcuA&oauth_callback_confirmed=true

Step 2: Authenticate user

URL https://web.foretagsplatsen.se/OAuth/Authorize/
Supported verbs GET
OAuth http://oauth.net/core/1.0a/#auth_step2

The authentication step is where the user will be allowed to log in and give the application permission to access the API. F�retagsplatsen only supports the standard flow (callback-flow, not out-of-band-flow). The standard flow will redirect the user to the Authorize-URL. The request will contain the RequestToken that was acquired in the first step.

Following the previous example, it would look something like this:

    https://web.foretagsplatsen.se/OAuth/Authorize/?oauth_token=8ldIZyxQeVrFZXFOZH5tAwj6vzJYuLQpl0WUEYtWc

The login form will be presented in case the user didn't login recently

After the user has logged in and approved the client application to access teh API the user will be redirected back to the appliaction. The URL that is being used for redirection is the same URL (oauth_callback) that was specified in the first step. 

oauth_token=8ldIZyxQeVrFZXFOZH5tAwj6vzJYuLQpl0WUEYtWc&oauth_verifier=pDNg57prOHapMbhv25RNf75lVRd6JDsni1AJJIDYoTY

Desktop applications are often using an embedded webbrowser (e.g. WebBrowserControl in C#) with a controller for custom protocols (e.g. myapp://some/path) and will, for example, set the URL (oauth_callback) to myapp://success.

Step 3: Request access token

URL https://web.foretagsplatsen.se/OAuth/AccessToken/
Supported verbs POST
OAuth http://oauth.net/core/1.0a/#auth_step3

The last step is to exchange a RequestToken for an AccessToken, which will be used later to sign calls to the API. An AccessToken should be stored in the client application to avoid the need for the user to login every time.

Read more about signing requests here: http://oauth.net/core/1.0a/#anchor12

OAuth client_auth

URL https://web.foretagsplatsen.se/OAuth/AccessToken/
Supported verbs POST
OAuth http://tools.ietf.org/html/draft-dehora-farrell-oauth-accesstoken-creds-01

OAuth client_auth is a suggestion for an extension to OAuth that is, among others, used by Twitter (http://dev.twitter.com/pages/xauth).

The method gives mobile phone- and desktop application ability to exchange username and password for an AccessToken directly. The down side of it is that the user has to provide username and password to the client application. One of the reasons for using it is that it is easier to implement in the client since it doesn't require an embedded webbrowser.

F�retagsplatsen does not recommend that you store the users' username and password in your application. Use the information to get an AccessToken and store that one instead.

The request is signed in the same way as the request for a RequestToke, with three additional parameters.

Extra parameters

x_auth_mode
Method being used (client_auth)
x_auth_username
Username
x_auth_password
Password

Parameters for signing