If you're hiring a developer to create a custom script or application, or managing access to third-party services in-house, you'll need to manage access to your store's data via the Retail API. Previously, this was done through personal tokens, a unique code that granted developers’ access to needed data. Now, you can use private apps that blend the usability of personal tokens with the security benefits of third party apps.

Understanding private apps

Previously, access to Retail POS was granted with personal tokens. The tokens were generated by a Retail POS Admin user, and gave the user full access to the account. API-related actions performed by a user were associated with the user who generated the token. If a user was deleted, their personal tokens were deleted as well.

Private apps remove the need to track multiple personal tokens across active and deleted users, instead leveraging third party apps created by developers in the Developer Portal. Retail POS Admins can approve app connections, which then connect to the Retail POS account instead of a specific user.

With private apps:

• Developers work inside the Developer Portal and do not need access to Retail POS.
• Tokens are not tied to an individual user.
• You can restrict apps to specific features like sales or products using scopes.
• Set up and integration is simpler than external third party apps. Private apps don't require OAuth for authentication.

You can seamlessly migrate your existing personal tokens to private apps without any downtime.

Once opted in to private apps, personal tokens will no longer be available. Personal tokens will be deprecated and removed in the future. Accounts created after January 27, 2026 will only have access to private apps.

Understanding organizations

An organization is a space in the Developer Portal where applications are stored and managed.

Instead of granting a developer direct access to your Retail POS account, you can create an organization in Retail POS and then invite developers to access it from the Developer Portal.

Once a developer has accepted the invitation, they can send a request to install their application in your Retail POS account. After you approve the request and the app is installed, developers can create application tokens to authenticate Retail API requests.

Enabling private apps and creating organizations

You can enable private apps and seamlessly migrate existing personal tokens without any downtime.

Once opted in to private apps, personal tokens will no longer be available.

1. In Retail POS, navigate to Setup > Personal tokens (or Apps for accounts created after January 27, 2026).

   

2. In the Developer access to your account is changing banner, click Start setup.

3. Enter a name for your organization.

   

4. Enter an email address for your primary developer. This developer will be responsible for inviting other developers to your organization.
5. Click Send invite.

The primary developer will receive an email with a link to join the organization. If the developer already has an account, the invitation will also be available on the Organizations page in the Developer Portal.

1. From the email, the developer will need to click View invitation and either create an account or sign in to their existing Developer Portal account.

   

2. Then, the developer must click Accept.

   

After accepting the invitation, developers will be redirected to a page showing existing personal tokens that have been migrated to private apps.

Creating new private apps

To create new private apps, first the developer will need to add an application to your organization. You will then have to approve the request. Afterwards, the developer can generate application tokens to authenticate Retail API requests.

Creating a new private app in the Developer Portal (developers)

If you're a developer, you can create an application to add to a Retail POS organization from the Developer Portal. Your private apps will need explicit approval from the Retail POS Admin, then you can generate application tokens.

1. In the Developer Portal, navigate to Organizations.

   

2. Click the name of the organization you’ll be creating the application for, then click Add Application.

   

3. Select the scopes, which determine what private apps can access in Retail POS. You can choose as many scopes as needed for your application.

   

4. Once all details have been filled, click Save.

   You’ll be redirected to the Organizations page, showing that the application has been created and is awaiting approval from the Retail POS Admin.

   

5. Communicate with the Retail POS Admin so they can approve the app.

Approving private app requests (Retail POS Admins)

After a developer has added a private app to your organization, you will get an approval request. Account Owners will receive an automated email, while other Admin users will receive an in-app notification in Retail POS.

1. From the email, click Review Installation Request.

   

   Or, click the bell icon at the top right of Retail POS > Approve request.

   

2. On the private app page, click Approve installation.

   

Generating application tokens (developers)

Once the private app has been approved and installed by the Retail POS Admin, a new token can be generated in the Developer Portal.

1. In the Developer Portal, navigate to Organizations.
2. Click the name of the organization to expand the row.

3. Click Edit application.

   

4. Click Generate New Token.

   

5. A window will appear displaying the private app token. Copy the token and store it in a safe place. You will not be able to see the token again.

Adding and managing personal tokens (legacy)

Personal tokens will be deprecated and removed in the future. New accounts only have access to private apps.

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

  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.

  To create a personal token:

  1. In Retail POS, navigate to Setup > Personal tokens.

     

  2. Click Add Personal token.

     

  3. 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.

     

  4. 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 your store. Removing any unused tokens can reduce the risk of misuse in the future.