Personal Tokens

If you are planning to hire a developer to create a custom script, desktop application or web application integration for your Retail POS store they will need to gain access to your store's data via the Retail POS API. You can provide them with this access by creating a Personal Token. This is a unique code that grants the developer access to the data they need and allows you to manage these integrations on an individual basis.

Note

Tokens should not be used as a primary authentication mechanism for web based applications. Those applications should be using OAuth 2.0 authorisation as described in our developer documentation.

What is a Personal Token?

The Personal Token is the equivalent to a password and gives someone access to your Retail POS account via the Retail POS API. While this doesn’t grant access to the sell screen it will provide the same level of access to the data as an admin user.

Important

By providing a developer with this token they will have full access to the data in your store. Make sure you send this privately and don’t publicly share the information anywhere.

How to access personal tokens

To create a token navigate to Setup -> Personal Tokens

Click Add Personal Token

Enter the requested information:

Token name: for this field put in a name for your reference. It is also important to make this unique to avoid any confusion if you have multiple tokens active.

Expiry date: This will be disabled by default however, if you only want the custom integration or script to be able to access your data for a limited time, you can specify a token expiry date.

Once this is done click Generate Personal Token. You can then copy the token to send it through to your developer(s).

Once the token is saved, you will not be able to view your Personal Tokens in clear text in the Personal Tokens page. All your existing tokens will still work as usual. 

If you are building multiple apps for your store it is recommended you create a token for each app.

Important

If the token you have provided a developer expires, the integration they have built will no longer work. You can extend or remove the expiry date by editing the current token or creating a new one.

If you do require long-term use, it is best to use OAuth 2.0 authorisation as described in our developer documentation.

Every request to sent to the Retail POS API needs to be authorised. The best way to do it is by adding the Authorization header, just like it's done for OAuth tokens:

Authorization: Bearer _here_goes_your_token_

Best Practices for managing personal tokens

Remove unused Personal Tokens

Make sure you remove any unused Personal Tokens. Personal Tokens provide full access to the retailer's store. By removing any unused tokens you will be reducing the risk of misuse going forward.

Rotate Personal Tokens periodically

It is best to change personal access tokens on a regular basis. To make this easier, we have implemented a change to the personal token user interface in Retail POS that displays 'token age'. For example, < 30 days (Green), < 90 days (Yellow), < 180 days (Red). You can also choose to have 'Inactive' tokens turn red in X days.

Do not use Personal Tokens for long-term use

In many scenarios, you will not need a long-term personal access token that never expires. Instead, you can generate credentials through the Retail POS developer portal. These credentials consist of an access key and a secret, but they also include a token that allows you to renew the access key automatically when the access key expires.

If you do require long-term use, it is best to use OAuth 2.0 authorisation as described in our developer documentation.

Understand how you're using a Personal Token

If a Personal Token is created under your Retail POS user, create a descriptive name so you know where it's being used. If the Personal Token needs to be changed, you'll need to know how to rotate/change it. If you don't know how to rotate or change a token, it's likely that an application is a better fit.

Set an expiry on each Personal Token you create

Make sure you have set an expiry for every personal token you create. Personal Tokens are not meant for application integrations and therefore should only need to be accessible for a limited time.

In case of any questions regarding Personal Tokens or the API in general, please get in touch with our Developer Relations Team at x-series.api@lightspeedhq.com