Skip to main content

Managing Access Tokens

Introduction​

The Lightspeed Restaurant K-Series APIs use the OAuth2 authorization code flow to authenticate API users. For third-party apps interfacing with multiple businesses, effective access token management is vital. Here is how to approach this systematically:

1. Initiate Authorization​

For every business account you wish to access:

  • Direct the end-user to your configured Lightspeed authorization URL.
  • Users will be prompted to login to Lightspeed and grant permissions based on the scope parameter provided in the authorization URL.
  • Once permissions are granted, the redirect URL is called with a temporary authorization code.
tip

The state parameter, typically a randomly generated string used for security purposes, can also be used to match which business account corresponds to each authorization request. By associating a randomly generated state value with each account, you can determine which account's authorization is being processed upon redirection.

2. Retrieve the Access Token​

After receiving the temporary authorization code:

  • Exchange this code for an access_token and refresh_token pair by sending a request to the /token endpoint.
  • The response will contain both the access_token and the refresh_token. It will also contain the scope and expires_in details.
tip

Securely store this data. Relate each access token and corresponding refresh token with the respective business location ID, or another unique identifier for tracking purposes.

3. Token Management and Refresh​

Replace outdated tokens with the newly acquired ones for that specific business.

Important note

Access tokens are granted the same access as the user who authorizes the access token.

If you want to connect to multiple business locations within the same business, you'll need a token or a combination of tokens that have been authorized by users with access to all those locations. The most straightforward scenario occurs when there's a user with access to all locations who can grant authorization. However, in other cases, you will need to request a combination of tokens to gain access to all the locations.

Best Practices for Managing Multiple Tokens​

  • Secure Storage: Access tokens and refresh tokens should remain within your server environment to ensure maximum security. Never store access tokens or refresh tokens in web applications on the frontend, and avoid storing them within your app, whenever possible.
  • Automated Refresh Mechanism: Implement automation for token expiration checks and proactive refreshing. Ideally, access tokens should be refreshed within a 30 second window of their expiration time.
  • Log and Monitor: Keep logs to monitor token generation, refreshing, and failures, to assist in identifying integration issues.

Error Handling​

If an access token becomes invalid or expired, a 4xx error will be returned. In this case, the authentication flow should be re-initiated. This means prompting the user to re-authenticate so the application can secure a new access token.

More Info

For more information on OAuth2, see the framework documentation.