Token Exchange Migration

Introduction

The Token Exchange migration method allows you to migrate from V1 to V2 authentication without requiring merchants to reauthorize your application. This method is best for applications that have a large number of users or where user experience is a high priority. It also allows PMS and Online Ordering integrations to maintain existing PMS providers and webhooks when migrating to V2.

At a glance

The Token Exchange method involves exchanging existing valid V1 access tokens for new V2 access tokens. This process can be done programmatically using previously granted V1 access tokens, as long as they are still within their validity period. The general steps for this migration method are as follows:

1. Back up your existing V1 access tokens
   • Ensure you have a secure backup of all active V1 access tokens and refresh tokens before starting the migration process, in case any issues arise during the token exchange process.
2. Exchange Tokens
   • Using the same client ID and client secret as your V1 API client, call the token exchange endpoint to receive a corresponding V2 token, this process needs to be repeated for each active V1 user token.
3. Update Authentication Configuration
   • Once you've exchanged all your access tokens for V2 tokens, update your application's authentication configuration to the new authentication endpoints.
4. Test the Integration
   • Test your integration to ensure that authentication and API requests function as expected under V2 authentication.

Token Exchange Endpoint

The token exchange endpoint allows you to exchange a valid V1 access token for a new V2 access token. Your V2 API client will have the same client ID and client secret as your V1 API client, and must be called for each active V1 user token that you want to exchange. Once this process is complete, you can update your authentication configuration to use the new V2 authentication endpoints.

Endpoint URLs

• Trial Environment: https://auth.lsk-demo.app/realms/k-series/protocol/openid-connect/token
• Production Environment: https://auth.lsk-prod.app/realms/k-series/protocol/openid-connect/token

Request

To exchange a V1 token for a V2 token, make a POST request to the appropriate token URL with the following parameters in the request body:

• grant_type: Must be set to urn:ietf:params:oauth:grant-type:token-exchange
• subject_token_type: Must be set to urn:lightspeed:oauth:token-type:ls-v1
• subject_token: The valid V1 access token that you want to exchange
• client_id: Your V2 client ID (same as your V1 client ID)
• client_secret: Your V2 client secret (same as your V1 client secret)

Example request:

POST https://auth.lsk-prod.app/realms/k-series/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token_type=urn:lightspeed:oauth:token-type:ls-v1
&subject_token={your-v1-access-token}
&client_id={your-client-id}
&client_secret={your-client-secret}

Example response:

{
    "access_token": "xxxxxxx",
    "expires_in": 1500,
    "refresh_expires_in": 0,
    "refresh_token": "xxxxxxx",
    "token_type": "Bearer",
    "id_token": "xxxxxxx",
    "not-before-policy": 0,
    "session_state": "afe06d63-d91f-4d5a-a89e-d5924421836f",
    "scope": "email orders-api propertymanagement financial-api offline_access profile",
    "issued_token_type": "urn:ietf:params:oauth:token-type:refresh_token"
}

Important Note

The exchange process should be done in one batch so that all tokens are exchanged before updating your authentication configuration.

Troubleshooting

If you encounter an issue during the token exchange process, you can use the manual migration method as a fallback option. Reach out to API Support if you need assistance with the token exchange process or if you want to discuss which migration method is best for your application.

Good to Know

After initiating the token exchange, existing V1 access tokens and refresh tokens will remain valid on V1 endpoints until their expiry time.