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. The latest version of the OAuth 2.0 specification can be found here.

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

2dehands.be

2ememain.be

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

2dehands.be

2ememain.be

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

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 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:

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.

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

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.

{
   "access_token"  : "...",
   "token_type"    : "...",
   "expires_in"    : ...,
   "refresh_token" : "...",
   "scope": "..."
}
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:

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 Obtaining an Access Token for a user.

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.

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

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 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.

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.

{
   "access_token"  : "...",
   "token_type"    : "...",
   "expires_in"    : ...,
   "scope": "..."
}
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:

  1. Passing access_token in the header, with Authorization: Bearer <access_token>
  2. 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:

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:

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.

Environment Access Token Refresh Token
Sandbox 24 hours never expire
Production 24 hours never expire