Authentication

Authentication with the Xentral APIs is available through Personal Access Tokens (PATs).These allow you to securely communicate with Xentral APIs from an external application. For example, these applications can be small scripts that you developed or a customization built for you by a Xentral partner. With personal access tokens you can use the API with multiple applications at the same time.

Using the PATs, you can authenticate with all Xentral APIs (current Xentral API, REST API, Standard API). This way, you don't need to switch authentication methods when you want to use an older API. We still recommend you use the current Xentral API, because the older REST and Standard APIs can’t handle all endpoints when using personal access tokens. You can find a list of unavailable endpoints at the end of this article.

Creating a Personal Access Token

📘

Pre-requisite

Make sure that you have admin rights before you try to create a personal access token.

Steps:

  1. In the Xentral NextGen design, click on the Administration menu on the bottom left and then click on Account settings.

  2. Go to Developer Settings > Personal Access Tokens. You will see a list of all tokens in active use.

  3. Click on + Create Token. If there are no tokens active, you will find the button in the middle of the screen. Otherwise you will find it on the top right of your list.

  4. Enter a unique Name for your token. The name should not exceed 50 characters.

  5. Click Create Token. The new token will appear on screen.

  6. Copy the token by clicking on the copy icon. After you close the window you won't be able to see the token again. Make sure that you save the token in a secure space before you continue.

    The name of the token will now appear in the list of Personal Access tokens. You can paste the token into the application you want to give access to the Xentral API.

🚧

Be aware

Personal access tokens enable API-based access to Xentral with unlimited permissions and without expiration date. As this may pose a potential security risk, it is good practice not to share tokens publicly and not to hardcode them into external applications. Make sure you fully trust the external applications that you grant access to Xentral.

You can disable an application’s access to the Xentral API at any time by deleting the corresponding token.

Editing and delete personal access tokens

You can edit an information of a token or disable an application’s access to the Xentral API at any time by deleting the corresponding token. All the personal access tokens you use will be listed under Administration > Account settings > Developer settings > Personal Access Tokens. You can edit all the tokens you are using. When you click Edit you have two options:

  • Change name - You can change the name of the token to better differentiate it from other tokens. Enter the new Name and click Update Token.
  • Delete token - You can remove the access of the software to the API by clicking Delete token. The software you connected with this token will no longer work in the Xentral environment. You can't restore a deleted token.

Unavailable endpoints in REST and Standard API

You can't access the following endpoints in the legacy APIs using personal access tokens. This list makes no claim to completeness.

/shopimport/auth
/shopimport/syncstorage/{articlenumber:.+}
/shopimport/articletoxentral/{articlenumber:.+}
/shopimport/articletoshop/{articlenumber:.+}
/shopimport/ordertoxentral/{ordernumber:.+}
/shopimport/articlesyncstate
/shopimport/statistics
/shopimport/modulelinks
/shopimport/disconnect
/shopimport/reconnect
/shopimport/status
/shopimport/refund
/v1/reports