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.

See Managing Access Tokens for best practices on managing access tokens.