Skip to content

Three-legged OAuth (user context)

This challenge authenticates the system and the user. Since users have to provide their credentials within the ImmobilienScout24 authentication web page, this method is recommended if you can forward the user to that page (within a web browser), and you have a callback URL for ImmobilienScout24 to redirect the user back to, after successful authentication and token authorization.

This flow involves three main steps:

  • Temporary Credentials Acquisition: The system gets a set of temporary credentials from the server, also known as a Request Token.
  • Authorization: The user actively "authorizes" the system which owns the request_token to access their account. This action is done via a web flow (web browser).
  • Token Exchange: The system exchanges the short-lived temporary credentials for a lifetime token, also known as Access Token.

Steps for OAuth Flow:

1. Temporary Credentials Acquisition

The first step to authorization is acquiring a set of temporary credentials known as the Request Token (oauth_token and oauth_token_secret ).

These credentials are short-lived (30 minutes), and are used solely for the initial authorization process. They won't grant any access to data on our server, and you cannot use them for anything except the authorization flow.

You must acquire these credentials by an initial HTTP request to the following server:

    https://rest.immobilienscout24.de/restapi/security/oauth/request_token

The POST request must include the following OAuth parameters:

  • oauth_consumer_key
  • oauth_callback (the authorization callback URI)
  • The request signature (oauth_signature and oauth_signature_method)
  • oauth_timestamp
  • oauth_nonce
  • oauth_version (optional)

The request looks as follows:

POST /oauth/request_token HTTP/1.1
Host: server.example.com
Authorization: OAuth oauth_consumer_key="your_system_key",
               oauth_signature_method="HMAC-SHA1",
               oauth_timestamp="987654321",
               oauth_nonce="7dk77uj4a",
               oauth_callback="http%3A%2F%2Fclient.example.com%2Fcb",
               oauth_signature="..."

The server checks the key and signature to ensure the client is valid. It also confirms the callback URI. Once the checks are complete, the server creates a new set of temporary credentials (oauth_token and oauth_token_secret) and returns them in the HTTP response (URL encoded). The response looks as follows:

HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded

oauth_token=kji98hr5&oauth_token_secret=ijhu787gf5ef5&oauth_callback_confirmed=true

You can then use these credentials as the oauth_token and oauth_token_secret parameters for the Authorization and Token Exchange steps (see below). All further steps using this Request Token must be executed within 30 minutes; otherwise, the token expires.

2. Authorization

The next step is a user-facing one (web browser-based). Redirect the user to the server to grant the client permission to act on the user's behalf. This is typically done via a redirect for in-browser clients or opening a browser for native clients.

Simply use the following URL and append the temporary credential key oauth_token, previously obtained in step 1, to the URL as a query parameter.

https://rest.immobilienscout24.de/restapi/security/oauth/confirm_access?oauth_token=...

The user then logs into ImmobilienScout24 portal if they aren't already and authorizes the client. They can also choose to cancel the authorization process.

If the user authorizes the client, ImmobilienScout24 then accepts the token as authorized, and redirects the user back to the callback URL (from step 1).

Response Parameters

- oauth_token - The obtained temporary credentials identifier.
- oauth_verifier -  a CSRF token that needs to be passed in the next step.
- state - the result of the authorization which can be
    - authorized: the token was successfully authorized by the user,
    - rejected: the token was explicit not authorized by the user or
    - error: an error has occurred while authorizing (often due to the request token being expired)

3. Token Exchange

The final step in the OAuth flow is to exchange the temporary credentials with lifetime credentials, known as Access Tokens.

A POST request must be sent to the ImmobilienScout24 server. This request must be signed by the temporary credentials and must include the oauth_verifier token obtained by the previous authorization step.

https://rest.immobilienscout24.de/restapi/security/oauth/access_token Required OAuth Parameters - oauth_consumer_key - oauth_token - The temporary credentials identifier. - oauth_signature_method - oauth_timestamp - oauth_nonce - oauth_signature - oauth_verifier - The verification code received from the ImmobilienScout24 API in step 2. - oauth_version (optional)

The request looks as follows:

POST oauth/access_token HTTP/1.1
Host: server.example.com
Authorization: OAuth oauth_consumer_key="your_system_key",
               oauth_token="hdk48Djdsa",
               oauth_signature_method="HMAC-SHA1",
               oauth_timestamp="987654321",
               oauth_nonce="7dk77uj4a",
               oauth_verifier="RW7C7W",
               oauth_signature="..."

The server responds with the final set of credentials: HTTP response body (form data, URL-encoded):

HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded

oauth_token=tg76hgf5rdffer4d&oauth_token_secret=k8ujhzgfd5gfd5rfg3

The access token is valid for an unlimited time until the user cancels the authorization. It's suggested that the system application (e.g., a mobile client) stores the access token and reuses it for subsequent calls to restricted resources of the REST API until the access token expires or is revoked by the user. After this step, the temporary credentials (Request Tokens) are invalidated as well as the verifier.

Resource Request

The resource request is to get or modify an arbitrary resource. Every resource request must be signed (see below).

    https://rest.immobilienscout24.de/restapi/api/...

Required OAuth Parameters

  • oauth_consumer_key
  • oauth_token - The token identifier received in step 3.
  • oauth_signature_method
  • oauth_timestamp
  • oauth_nonce
  • oauth_signature
  • oauth_version (optional)

Response Parameters

  • See API Documentation of the requested resource.

Signing Requests

All OAuth challenges require the signing of requests. The request signing is composed of the following two steps:

  • Extracting a signature base string for the current request
  • Calculating a signature for that signature base string using the specified signature method and the combination of system secret and token secret.

Signature Key

You create a signature key by URL encoding your system_secret and the request_token_secret, then concatenating them with & into a string.

For example, if your system_secret is abcde and your request_token_secret is 12345, the key is abcde&12345.

Note:

  • The request_token_secret always ends with an equal sign. Hence the encoded token secret ends with %3D (it is the last sign in a Base64 encoded strings).