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

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¶

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.
scope	Optional	Additional, optional scopes of the request, see Scopes. If not filled in, the scope of the access token will be the default scopes registered for your Client.
state	Optional, but recommended	Any client state that needs to be passed on to the client request URI. This will be appended as a state query param to the redirect_uri. This is one of two ways to add your own metadata to the redirect_uri, the other is adding query params to the redirect_uri itself.
redirect_uri	Required	The URL to which the authorization server redirects the user with an authorization code after successful authorization. See the note below.

Note

The redirect_uri should exactly match one of the URIs registered with the client on our side. However, you can add your own query parameters to the redirect_uri. These will be preserved and sent to you once the redirect completes. Please do NOT use a query param called code since it will conflict with ours.

For proper encoding, make sure to URL encode any special characters, especially the query param separator & (which is %26 URL-encoded).

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.
(other)	Optional	Any other query params you added to the redirect_uri in step 1.

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:

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:

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