Useful

Authentication

Authentication at the IS24 API

The IS24 API needs authentication for every request and therefore relies on OAuth 1.0a.

 

This page

  • gives an overview of the OAuth-Terminology,
  • depicts the authentication process at the IS24 API
  • shows how to get started with OAuth in the IS24 context

It is assumed that you are familiar with the principles behind OAuth. For more background information about OAuth, see the Beginner's Guide to OAuth.

At http://oauth.net/code a list of oAuth libraries

We have a tutorial for accessing data of an immobilienscout24 user. A detailed description of the single request steps, the required oauth-, query- and response-parameters can be found API-Authentication-Details.

 

 OAuth-Terminology

The OAuth Specification distinguishes between two authentication objects:

  • Consumer:
    an application which acts on behalf of the user and
  • User:
    uses the 3rd party application (Consumer).

 

 Consumer → System

In the IS24 terminology the OAuth Consumer is called System.

For authentication purposes a System uses

  • System key and
  • System secret.

The key acts as unique identifier of the System and the secret as a kind of password for this System.

 User

A user within the IS24 API is the IS24-user who uses the 3rd party application (System).

 

 Authentication Process

The IS24 API expects for each API call authentication but distinguishes between two levels:

  • Two-legged OAuth:
    requires only a System-key to sign the request. The user doesn't need to give any permission to access his/her resources.
  • Three-legged OAuth:
    requires both a System-key and a so-called access_token which represents the explicit permission of the IS24-user to access his/her resources.

 

IS24 Three-Legged-OAuth process

Sending Requests using Two-legged OAuth

Only one single step is required:

  1. request the resource (e.g. https://rest.immobilienscout24.de/restapi/api/search/v1.0/search ), only System key required

 

 Sending Requests using Three-legged OAuth

If user authentication is required, sending a request is a little bit more complex. here's a tutorial for easy getting an access token

Acquire an authorized request_token which represents the explicit permission of the IS24-user to access his/her resources.

  • (1) Get a request_token
  • (2, 3) Authorize the request_token (a user grants the system to use his account)

The authorized request_token can be used for a longer transaction with multiple requests. In our case it is valid until explicitely revoked.

  • (4, 5, 6) Get a pair of access_token and access_token_secret by using the authorized request token (can only be used once)

For each request do this:

  • (7) Request the resource (e.g. https://rest.immobilienscout24.de/restapi/api/search/v1.0/search).
  • Required are
    website/application identification: system_key, system_secret
    the just generated authorization by the consumer: access_token, access_token_secret

 

 IS24-API: URI's to get the Tokens

  • Getting the request token: https://rest.immobilienscout24.de/restapi/security/oauth/request_token
  • Confirm the access token: https://rest.immobilienscout24.de/restapi/security/oauth/confirm_access?oauth_token=...
  • Getting the access token: https://rest.immobilienscout24.de/restapi/security/oauth/access_token