Access Tokens

IMPORTANT

This article is for V2 API Clients. For V1 API Clients, see Managing Access Tokens - V1.

Introduction

This article provides an overview of access tokens, including information about behavior, best practices, and error handling. For a more detailed breakdown of the steps for retrieving and refreshing access tokens, see the Authorization Overview.

About Access Tokens

An access token is a credential that allows your application to access the Lightspeed API on behalf of a user. It is obtained through the OAuth2 authorization flow and is used to authenticate API requests.

Access tokens have a limited lifespan. After they expire, they can no longer be used to access the APIs. To maintain access, you can use a refresh token to obtain a new access token without requiring the user to re-authenticate.

Access Token Behavior

There are two sets of behaviors for access tokens, depending on whether the offline_access scope is included in the token request or not. This allows you to choose the token type that best fits your application's needs.

Definitions:

• Access Token Type: Whether the offline_access scope is included in the token request, which determines the longevity of the refresh token and the overall session duration. (Not to be confused with other access scopes, which determine the API permissions granted to the access token.)
• Access Token Validity: The duration for which the access token is valid and can be used to access the API. It is returned in the expires_in field of the token response.
• Refresh Token Validity: The duration for which the refresh token is valid and can be used to obtain new access tokens. It is returned in the refresh_expires_in field of the token response. Note: for tokens with the offline_access scope, the refresh_token_validity field will have a value of 0.
• Session Duration: The total duration of the access session, which is the time from when the access token is issued until reauthorization is required.

Definitions Table

Access Token Type	Access Token Validity	Refresh Token Validity	Session Duration	Example Use Case
With offline_access Scope	25 minutes	40 days	No limit, as long as the refresh token is refreshed at least once every 30 days	Suitable for applications that require long-term access without user re-authentication, such as background services or applications that need to maintain access even when the merchant is not actively using the app.
Without offline_access Scope	25 minutes	30 minutes	10 hours	Ideal for applications that require short-term access and can prompt users to re-authenticate as needed, such as web applications or mobile apps that are actively used by the merchant.

Sample Token Response

When a token request is made, the response will include the access token, refresh token, and other relevant information. The access token is a JWT (JSON Web Token), and can be decoded using a JWT decoder to view its contents, which will include the token's expiration time, the user's identity and permissions, the scopes granted to the token, and other details.

Sample Response:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3NjM1OTM4MzEsImlhdCI6MTc2MzU5MjMzMSwiYXV0aF90aW1lIjoxNzYzNTkyMjc1LCJqdGkiOiJvbnJ0cnQ6M2FkNmRjYWUtYTEyMy0zZTMwLTY3YTktNGQ1ZjZiODJmNDlhIiwiaXNzIjoiaHR0cHM6Ly9hdXRoLmxzay1kZW1vLmFwcC9yZWFsbXMvay1zZXJpZXMiLCJhdWQiOiJhY2NvdW50Iiwic3ViIjoiZjE0MTIzNDUtNDhkYS00NmVmLWExNWItNWQ1OTE4NThiMDc2IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoicGFydG5lcnNoaXBzLWludGVncmF0aW9uLWRlbW8tY2xpZW50Iiwic2lkIjoiOWYzNDU2MzdhLWRjODUtNGY1Yy04MjZmLTdkYjk5N2RiNzAzOSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsiaHR0cHM6Ly9sb2NhbGhvc3QiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwiZGVmYXVsdC1yb2xlcy1rLXNlcmllcyIsInVtYV9hdXRob3JpemF0aW9uIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwic2NvcGUiOiJmaW5hbmNpYWwtYXBpIGVtYWlsIHByb2ZpbGUiLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwiZW1haWwiOiJkb2N1bWVudGF0aW9udGVzdEBsaWdodHNwZWVkaHEuY29tIn0.3LeQ9ug3JBLyPus-hAzlmIxuC6WpVqfRG2Qm-MdtUxA",     //pragma: allowlist secret
    "expires_in": 1500,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3NjM1OTQxMzEsImlhdCI6MTc2MzU5MjMzMSwianRpIjoiN2Q5OTFmNjEtMGEyOS04ZzI1LTBhOGItMjU4YWY2OGE1MmE4IiwiaXNzIjoiaHR0cHM6Ly9hdXRoLmxzay1kZW1vLmFwcC9yZWFsbXMvay1zZXJpZXMiLCJhdWQiOiJodHRwczovL2F1dGgubHNrLWRlbW8uYXBwL3JlYWxtcy9rLXNlcmllcyIsInN1YiI6ImYxNDJmYTMwLTYwZGEtNDZlZi1hMTViLTVkMTUxODU4YjA3NiIsInR5cCI6IlJlZnJlc2giLCJhenAiOiJwYXJ0bmVyc2hpcHMtaW50ZWdyYXRpb24tZGVtby1jbGllbnQiLCJzaWQiOiI5ZjIyY2I3YS1kYzM0LTRmNWMtODI2Zi03ZGI5OTdkYjcwMzkiLCJzY29wZSI6ImZpbmFuY2lhbC1hcGkgZW1haWwgcHJvZmlsZSJ9.A-2Lu16KY2B79pRV5NYU-42rar_cDtSrjBN99KVAKOk", //pragma: allowlist secret
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "26a01a6c-9603-4596-a48d-86bbcaa54ef8",
    "scope": "financial-api email profile"
}

Managing Access Tokens

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. Access tokens must be refreshed before the refresh token expires.
• Log and Monitor: Keep logs to monitor token generation, refreshing, and failures, to assist in identifying integration issues.

Best Practices

Maintaining Access

• Monitor refresh_token lifetime and ensure the access_token is refreshed before the refresh token expires.
• Each refresh returns a new access_token and refresh_token. Always update your stored tokens.

Handling Expiry Times

• Never hardcode expiry values as they may change due to security updates.
• Always check the token response for expires_in (access token lifetime) and refresh_expires_in (refresh token lifetime) and dynamically schedule refreshes based on these values.

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.