Client App Auth

This is an alternative authentication method for plentymarkets REST API. It is using OAuth 2.0 to generate a JWT token that can be used to authenticate in the REST API.

This authentication method is in BETA phase.

Setup

To be able to use this new authentication method, you must have an active app client.

You can access App Clients Settings under Setup » Account management » App clients.

Create a app client

You can add a new app client by pressing the + New app client button.

The Create page has the following options:

Option Explanation

Name

The name of the App Client used for future reference and identification.

Role template

Use an existing role as template

Select from an existing Role found in Setup » Account management » Roles.

This will autocomplete the Rights and Access rights options.

Rights

What REST API endpoints and actions can the client app access.

Access rights

What REST API areas can the client app access.

An app client secret is automatically generated when creating the App client.

app client secret

After you saved, a popup appears with the App Client secret.
Copy the secret, because you won’t have access to it afterwards.
In case you lose your App Client secret you have to regenerate it.

After creating the App Client, you will be redirected to the App Client detail view.

App Client Details Page

Once you created an App Client, you can view the Client ID and Token URL used for generating the JWT token.

The App Client detail view has the following options:

Option Explanation

Name

The name of the App Client used for future reference and identification.

Client ID

Client ID used in the Token URL payload.

Token URL

URL used to generate the JWT token used for REST API authentication.

Enable app client

on/off

Enable or disable the client app overall access.

Rights

What REST API endpoints and actions can the client app access.

Access rights

What REST API areas can the client app access.

Regenerate App Client secrets

If you forgot the App Client secret or just want to regenerate it you can do this by clicking on Regenerate secret:

regenerate secret

After clicking the button a popup appears with the App Client secret. Copy the App Client secret, because you won’t have access to it afterwards.

How to authenticate with your Client App

Authentication in the REST API with an Client App requires two steps:

  1. Generate the JWT token from the Token URL in the Client App settings

  2. Use the JWT token to authenticate the REST API calls

Generate JWT Token

Make a POST request to the Token URL as in the following example:

POST [TOKEN_URL]
Content-Type: application/x-www-form-urlencoded
Payload:
{
   client_id: [CLIENT_ID],
   client_secret: [CLIENT_SECRET],
   grant_type: client_credentials,
}
Variable Explanation

TOKEN_URL

The TOKEN URL from the Client App Details Page.

CLIENT_ID

The CLIENT ID from the Client App Details Page.

CLIENT_SECRET

The latest Client App secret that was generated.

Success response:

{
    "access_token": [JWT_TOKEN],
    "expires_in": [JWT_TOKEN_EXPIRATION],
    "token_type": "Bearer"
}
Variable Explanation

JWT_TOKEN

The JWT token that can be used to authenticate the REST API calls.

JWT_TOKEN_EXPIRATION

The amount of seconds that it will take until the JWT will expire from the time the JWT it is generated.
The default value is 3600 seconds, but it may vary.

Once a JWT token is expired, it can not be used.

Authenticating in the REST API

For authenticating the REST API with the Client App JWT token you have to sign every request sent to the REST API endpoints using the Bearer Token Authorization Type by setting the Authorization header:

Authorization: Bearer [JWT_TOKEN]

FAQ

Is there a token refresh for the JWT token?

No, at this time there is no way to refresh the JWT token without requesting a new one from the TOKEN URL.

Can you invalidate a JWT token?

No, at this moment we do not provide a way to invalidate a JWT token. A token is valid for 3600 seconds (1 hour), after which it will no longer be usable.
In case of emergency, you can disable the Client App until the JWT token expires.

How can I find what Client App is authenticated in the REST API?

You can use the rest/users/me endpoint to get information about the user for wich the JWT token.

Note: in the json data that you will receive from the rest/users/me endpoint, the CLIENT ID is found in the username parameter.