Skip to main content

About Access Tokens

Introduction​

This article explains how to retrieve the permissions associated with an access token. It also provides best practices for managing access tokens and handling errors. For detailed steps on retrieving and refreshing access tokens, see the Authorization Overview.

Permissions of an Access Token​

Access tokens have the same level of access as the user who authorizes them. If you need to connect to multiple business locations within the same organization, you must ensure your token (or combination of tokens) is authorized by users with access to all the necessary locations.

The simplest scenario is when a single user has access to all the necessary locations and can grant authorization. If no such user exists, you'll need to obtain tokens from multiple users in order to access all the necessary locations.

Retrieving Business Location Access​

You can retrieve detailed information about the business locations associated with an access token using one of the following endpoints:

Retrieving User Permissions​

At minimum, the following permissions are required to access the Lightspeed APIs:

Permissions

You can retrieve detailed information about access token permissions by making the following API request:

curl --location --request GET 'https://api.lsk.lightspeed.app/oauth/userinfo' \
--header 'Authorization: Bearer {{access_token}}'

Replace {{access_token}} with the access token you want to query. This request returns information about the user associated with the token, including their roles, permissions, and other attributes.

Example Response​

Below is an example response for the userinfo endpoint:

{
    "name": "email@demo.com",
    "attributes": {
        "staff": {
            "roles": [
                "ROLE_BACK_OFFICE",
                "ROLE_BO_WRITE",
                "ROLE_BO_LOGIN_TOKENS_WRITE",
                "ROLE_REPORT",
                "ROLE_CONFIG_USERS",
                "ROLE_CONFIG",
                "ROLE_BO_LOGIN_TOKENS"
            ],
            "emailAddress": "email@demo.com",
            "firstName": "John",
            "lastName": "Doe",
            "userId": 4345
        },
        "passwordToken": null,
        "accountNonLocked": true,
        "accountNonExpired": true,
        "credentialsNonExpired": true,
        "enabled": true,
        "password": null,
        "username": "email@demo.com"
    },
    "authorities": [
        "ROLE_BACK_OFFICE",
        "ROLE_BO_WRITE",
        "ROLE_BO_LOGIN_TOKENS_WRITE",
        "ROLE_REPORT",
        "ROLE_CONFIG_USERS",
        "ROLE_CONFIG",
        "ROLE_BO_LOGIN_TOKENS"
    ],
    "scopes": [
        "financial-api",
        "propertymanagement",
        "reservations-api",
        "staff-api",
        "orders-api",
        "items",
        "reservation-myplatform"
    ]
}

Key Fields in the Response​

  • name: The username of the user associated with the token.
  • attributes: Detailed user information, including roles, account status, and user identifiers.
    • staff.roles: A list of roles assigned to the user.
    • staff.emailAddress: The user’s email address.
    • staff.userId: The unique identifier of the user.
    • accountNonLocked, accountNonExpired, credentialsNonExpired, enabled: Indicators of the account’s status.
  • authorities: A list of permissions granted to the user.
  • scopes: The scopes that the token allows access to, defining the range of resources the token can interact with. See Access Scopes for more information.

Managing Access Tokens​

This is a general overview of access token management, including information about best practices and error handling. For a more detailed breakdown of the steps for retrieving and refreshing access tokens, see the Authorization Overview.

Authorization Steps​

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.

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