.. index:: Authentication

Authentication
==============

Authentication and authorization is provided using *OAuth2* to allow easy integration with
existing libraries. For more information please refer to the `OAuth 2.0
website <http://oauth.net/2/>`_. The latest version of the OAuth 2.0
specification can be found `here <http://tools.ietf.org/html/rfc6749>`_.

What is OAuth 2.0?
------------------

OAuth 2.0 is an open authorization protocol which enables applications to
access each others data. OAuth 2.0 specification replaces and obsoletes the
OAuth 1.0 protocol and is *not* backward compatible with OAuth 1.0.

OAuth 2.0 Roles
---------------
OAuth 2.0 defines the following roles of users and applications:

* **Resource Owner:** This is the person or application that owns the data
  that is to be shared. In this context *resource owner*
  is the Martkplaats user.

* **Resource Server:** This is the server hosting the resource owned by the
  resource owner. In this context *resource server* is the server hosting
  Marktplaats API.

* **Client:** This is the application requesting access to the resources stored
  on the resource server. In this context *client* is the application wanting
  to use the Marktplaats API.

* **Authorization Server:** The authorization server is the server
  authorizing the client app to access the resources of the resource owner.
  In this context *authorization server* is the server hosting authentication
  and token endpoints.

OAuth 2.0 Endpoints
-------------------

**Authorization Endpoint:** This is the endpoint on the authorization server
where the resource owner logs in, and grants authorization to the client
application. The authorization endpoint urls are as follows:

**Marktplaats.nl**

* *Sandbox:* https://auth.demo.qa-mp.so/accounts/oauth/authorize
* *Production:* https://auth.marktplaats.nl/accounts/oauth/authorize

**2dehands.be**

* *Sandbox:* https://auth.demo-2dehands.qa-mp.so/accounts/oauth/authorize
* *Production:* https://auth.2dehands.be/accounts/oauth/authorize

**2ememain.be**

* *Sandbox:* https://auth.demo-2ememain.qa-mp.so/accounts/oauth/authorize
* *Production:* https://auth.2ememain.be/accounts/oauth/authorize

**Token Endpoint:**  This is the endpoint on the authorization server
where the client application exchanges the authorization code,
client ID and client secret, for an access token.
The token endpoint urls are as follows:

**Marktplaats.nl**

* *Sandbox:* https://auth.demo.qa-mp.so/accounts/oauth/token
* *Production:* https://auth.marktplaats.nl/accounts/oauth/token

**2dehands.be**

* *Sandbox:* https://auth.demo-2dehands.qa-mp.so/accounts/oauth/token
* *Production:* https://auth.2dehands.be/accounts/oauth/token

**2ememain.be**

* *Sandbox:* https://auth.demo-2ememain.qa-mp.so/accounts/oauth/token
* *Production:* https://auth.2ememain.be/accounts/oauth/token

.. _Obtaining an Access Token for a user:

Obtaining an Access Token for a user
------------------------------------

The steps for obtaining an access token for a user are as follows:

Step 1: Redirect to the authorization URL
`````````````````````````````````````````

Redirect the resource owner (user) to the authorization URL with the following GET parameters

.. list-table::
 :widths: 10 30 60
 :header-rows: 1

 * - Field
   - Required
   - Description

 * - response_type
   - Required
   - Must be set to ``code``.

 * - client_id
   - Required
   - ClientId assigned by Marktplaats.

 * - redirect_uri
   - Required
   - The URL to which the authorization server redirects the user with an authorization code after successful authorization. The provided redirect_uri has to start with the URL registered with the Client. If not, authentication will not succeed.

 * - scope
   - Optional
   - The possible scope of the request, see :ref:`Scopes <scopes>`. If not filled in, the scope of the access token will be empty.

 * - state
   - Optional, but recommended
   - Any client state that needs to be passed on to the client request URI.

.. note:: When registering a client_id, at least one redirect_uri has to be provided. The redirect_uri provided with the authentication calls should start with the registered uri.


Step 2: Redirect to the redirect_uri
````````````````````````````````````

After the resource owner logs in and confirms access request of the client
the authorization server redirects the resource owner to the ``redirect_uri``
specified in the request at step 1 with the following GET parameters:

.. list-table::
 :widths: 10 30 60
 :header-rows: 1

 * - Field
   - Required
   - Description

 * - code
   - Required
   - The authorization code.

 * - state
   - Required, if present in step 1
   - The same value as sent by the client in the state parameter at step 1, if any.

Step 3: POST to the token endpoint
``````````````````````````````````

This step is using the grant type ``authorization_code`` as described `in the specification section 1.3.1 <http://tools.ietf.org/html/rfc6749#section-1.3.1>`_.

After obtaining the authorization code at step 2 the client needs to make
a *POST* request to the *token endpoint* with the following parameters:

.. list-table::
 :widths: 10 30 60
 :header-rows: 1

 * - Field
   - Required
   - Description

 * - grant_type
   - Required
   - Must be set to ``authorization_code``.

 * - code
   - Required
   - The authorization code received from the authorization server at step 2.

 * - client_id
   - Required
   - Client id assigned by Marktplaats.

 * - client_secret
   - Required
   - Client secret assigned by Marktplaats.

 * - redirect_uri
   - Required
   - If present, should be identical to the redirect_uri specified in step 1.


Step 4: Receive token response
``````````````````````````````

The authorization server returns the following token response in JSON
format if the token request at step 3 is valid.

.. code-block:: javascript

    {
       "access_token"  : "...",
       "token_type"    : "...",
       "expires_in"    : ...,
       "refresh_token" : "...",
       "scope": "..."
    }

.. list-table::
 :widths: 10 60
 :header-rows: 1

 * - Field
   - Description

 * - access_token
   - The access token as assigned by the authorization server.

 * - token_type
   - The token type assigned by the authorization server. In this context set to ``bearer``.

 * - expires_in
   - Expiration time in seconds after which the access token becomes invalid.

 * - refresh_token
   - The refresh token for obtaining a new access token.

 * - scope
   - The scope of the access token.

.. note::

    Every time you request a new access token you also receive a new refresh token.
    This automatically invalidates the existing refresh token even if it has not
    expired yet.

Refreshing an Access Token
--------------------------

The refresh token is used to obtain a new access token once the access token is no longer valid.
In order to obtain a new access token the following *POST* request is necessary to the *token endpoint*
with the following parameters:

.. list-table::
 :widths: 10 30 60
 :header-rows: 1

 * - Field
   - Required
   - Description

 * - refresh_token
   - Required
   - Refresh token obtained when the original access token was received

 * - grant_type
   - Required
   - Must be set to ``refresh_token``

 * - client_id
   - Required
   - Client id assigned by Marktplaats

 * - client_secret
   - Required
   - Client secret assigned by Marktplaats

If the refresh token request is valid the authorization server returns a new access token. The token
response is identical to the token response explained at step 4 of :ref:`Obtaining an Access Token for a user`.

.. _Obtaining an Access Token for a client:

Obtaining an Access Token for a client
--------------------------------------

.. note::

   If client access token is requested then only client specific and public resources will be available.
   For example, it won't be allowed to place an advertisement or buy a feature on behalf of end user using client access token.
   It will be possible to create a new user (client specific end point) and get categories (public end point).

The steps for obtaining an access token for a client are as follows:

Step 1: POST to the token endpoint
``````````````````````````````````

This step is using the grant type ``client_credentials`` as described `in the specification section 1.3.4 <http://tools.ietf.org/html/rfc6749#section-1.3.4>`_.

The client needs to make
a *POST* request to the *token endpoint* with the following parameters:

.. list-table::
 :widths: 10 30 60
 :header-rows: 1

 * - Field
   - Required
   - Description

 * - grant_type
   - Required
   - Must be set to ``client_credentials``

 * - client_id
   - Required
   - Client id assigned by Marktplaats

 * - client_secret
   - Required
   - Client secret assigned by Marktplaats

 * - scope
   - Optional
   - The possible scope of the request, see :ref:`Scopes <scopes>`.

 * - redirect_uri
   - Optional
   - The URL to which the authorization server redirects the user with an authorization code after successful authorization. If not provided, the redirect_uri specified with the client registration is used.


.. _receive token response:

Step 2: Receive token response
``````````````````````````````

The authorization server returns the following token response in JSON
format if the token request at step 1 is valid.

.. code-block:: javascript

    {
       "access_token"  : "...",
       "token_type"    : "...",
       "expires_in"    : ...,
       "scope": "..."
    }

.. list-table::
 :widths: 10 60
 :header-rows: 1

 * - Field
   - Description

 * - access_token
   - The access token as assigned by the authorization server

 * - token_type
   - The token type assigned by the authorization server. In this context set to ``bearer``.

 * - expires_in
   - Expiration time in seconds after which the access token becomes invalid

 * - scope
   - The scope of the access token


Authorization using access_token
--------------------------------

There are two ways to use the access_token to authorize a request:

 #. Passing access_token in the header, with ``Authorization: Bearer <access_token>``
 #. Adding the access_token as a query parameter to the request.

Both methods are supported. The first method is the preferred one, because it prevents
potential issues with caching. However, the second method is supported for convenience.
The second method makes it easy do GET requests to the API using a regular webbrowser.

**Example**

Below is an example of authorizing a request with a Bearer token as a request header:

.. code-block:: http

    GET /advertisements/m1 HTTP/1.1
    Host: api.marktplaats.nl
    Authorization: Bearer mF_9.B5f-4.1JqM

When the access_token is passed as a query parameter of the URL, the request will be something
like the next example:

.. code-block:: http

    GET /advertisements/m1?access_token=mF_9.B5f-4.1JqM HTTP/1.1
    Host: api.marktplaats.nl

Expiration Times
----------------

Access tokens expire after the time listed in the table below. After this period the token
is no longer valid. A refresh token which is provided along with an access token is still valid after
the access token is expired. The 20 last provided refresh tokens stay valid, after that the oldest (21st)
refresh token is discarded.

Also note that every time you request a new access token you also receive a new refresh token and
your current refresh token is automatically invalidated even if it has not expired yet.

.. list-table::
 :widths: 40 20 20
 :header-rows: 1

 * - Environment
   - Access Token
   - Refresh Token

 * - Sandbox
   - 24 hours
   - never expire

 * - Production
   - 24 hours
   - never expire