- Available on Plus plans
If you're 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 API. You can provide access by creating a Personal Token, a unique code that grants the developer access to the data they need and allows you to manage these integrations on an individual basis.
Tokens should not be used as a primary authentication mechanism for web based applications. Applications should be using OAuth 2.0 authorization as described in the developer documentation.
Understanding personal tokens
A personal token is the equivalent of a password and gives someone access to your Retail POS account via the Retail 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.
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.
If a personal token needs to be changed, you'll need to know how to rotate or change it. If you don't know how to rotate or change a token or have access to a developer, an application may be a better fit.
Adding personal tokens
To create a personal token:
- In Retail POS, navigate to Setup > Personal Tokens.
- Click Add Personal Token.
- Enter the details and expiry information:
- Token name: Name for your reference. Make this unique to avoid confusion with other tokens.
-
Expiry date: Disabled by default. 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.
If the token expires, the integration the developer 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 require long-term use, it's best to use OAuth 2.0 authorization as described in the developer documentation.
- Click Generate Personal Token. You can then copy the token to send it through to your developer.
Once the token is saved and the popup window closed, you will no longer be able to view the token text on the personal tokens page for security. Existing tokens will still work as usual.
If you're building multiple apps for your store, it's recommended you create a token for each app.
Authorizing personal tokens
Every request to sent to the Retail API needs to be authorized. To do so, add the Authorization header in the same way as OAuth tokens.
Authorization: Bearer _here_goes_your_token_
Managing personal tokens
Manage personal tokens by following best practices:
Add descriptive names to tokens
If a personal token is created under a Retail POS user, add a descriptive name for the token so you know where it's being used.
Set token expiry dates
Set an expiry for each personal token you create. Personal tokens are not meant for application integrations and should only need to be accessible for a limited time.
Avoid long-term use of tokens
When you need long-term access with no expiry, you can generate credentials through the Retail POS developer portal. These credentials consist of an access key and a secret, and include a token that allows you to renew the access key automatically when it expires.
If you do require long-term use, it is best to use OAuth 2.0 authorization as described in the developer documentation.
Periodically rotate tokens
It's a good idea to change personal access tokens on a regular basis. In Retail POS, you can view the token age and update your tokens as needed.
Remove unused tokens
Make sure you remove any unused personal tokens, as they provide full access to the your store. Removing any unused tokens can reduce the risk of misuse in the future.