What Does This Mean for My Integration?
Steps to Migrate to OAuth 2.0
Who Needs to Migrate?
Transition Period ..........................................

OAuth 2.0 Migration Guide

DSV is enhancing the security of its public APIs by transitioning to OAuth 2.0. This new model offers improved protection against unauthorized access. As part of this change, the legacy DSV-Service-Auth  basic authentication method will be deprecated.

Starting on December 18th, 2024, we will begin implementing the OAuth authentication method. This will be a gradual process, progressively affecting all Generic APIs until full implementation is achieved.

All new API integrations will require a bearer token for authentication using OAuth 2.0. For existing users, this change will be rolled out in phases. We strongly encourage you to update your integration to OAuth 2.0 as soon as possible to enhance security and protect against unauthorized access.

Please ensure you monitor updates and notifications closely to stay informed about these changes. The affected APIs include: Booking, Tracking, Upload, Download, Invoice, Visibility & Webhook 2.0 API.

What Does This Mean for My Integration?

In the current model, API credentials are passed in the Authorization header as DSV-Service-Auth. With OAuth 2.0, this approach will be replaced with a token-based system. Here Is how the change will impact your integration.

1.     New Authentication Flow

Instead of including a static credential in each API call, you will obtain an access token via OAuth 2.0 and pass it in the {Authorization} header.

2.     Using Bearer Tokens in Requests

All API requests will now include an Authorization header with the format Bearer {access_token}

3.     Token Management
Tokens have a limited lifespan and must be refreshed periodically. Implementing automated token refresh logic is recommended to avoid downtime.

4.     Endpoint Changes

The API endpoints for Demo and QA environments have been updated. While production endpoints remain unchanged, adjustments to request headers and token management are needed to align with environment-specific authentication.

Steps to Migrate to OAuth 2.0

Step 1: Obtain your Token Subscription-key OAuth Credentials

To start using OAuth 2.0:

  • Log in to the developer portal and Verify your subscription to the "Access Token API" in your profile page.

  • Verify your subscription to the DSV Access Token API (you will see your primary and secondary subscription keys there).

  • If you are not subscribed to Access Token API:

    • Demo: Go to the API Catalog and subscribe to “DSV Access Token” API.

    • Production: Contact API Support to request your subscription key.

Step 2: Generate an Access Token

Send a POST request to the OAuth token endpoint:

Endpoint:

Request Headers:

  • Subscription-key: { environment_subkey }

Request Body:

  • grant_type: client_credentials

Authorization:

  • client_id: myDSV username

  • client_secret: myDSV password

Body Request:

Application x--www-form-urlencoded:

client_id={myDSV User}&client_secret={myDSV Pass}&grant_type=client_credentials

Step 3: Use the Access Token

Include the access token in the Authorization header of all the Generic API requests:

Authorization: Bearer {access_token}

Step 4: Refresh Tokens

When your access token expires, use the refresh token to obtain a new one:

Request Headers:

  • Subscription-key: {environment_subkey}

Request Body:

  • grant_type: refresh_token

  • refresh_token: Your Refresh Token from previous call

Example Request:

Application x--www-form-urlencoded:

refresh_token={Your Refresh token}&grant_type= refresh_token

Who Needs to Migrate?

All integrations currently using DSV-Service-Auth must migrate to OAuth 2.0. This includes:

  • Direct API users.

  • Third-party integrations (notify your vendors/partners immediately).

  • Any legacy system still utilizing DSV-Service-Basic Auth.

If you are using third-party plugins or platforms, those vendors are responsible for implementing the new OAuth 2.0 flow. Ensure your accounts are linked properly to avoid disruptions.

Transition Period

To ensure a smooth and seamless transition, the legacy authentication method will continue to be supported until September 1st, 2025. This extended transition period is designed to give all users sufficient time to adapt to the new OAuth 2.0 authentication system and update their integrations accordingly.

During this time, both the legacy and OAuth 2.0 methods will function in parallel. However, we strongly encourage all users to begin the migration process as early as possible to avoid potential disruptions. By transitioning ahead of the deadline, you can take full advantage of the enhanced security and efficiency provided by OAuth 2.0.

Please note that after September 1st, 2025, the legacy authentication method will no longer be supported. At that point, only integrations using OAuth 2.0 will be accepted. We recommend closely reviewing your current setup and making the necessary updates well before the cutoff date to ensure a smooth transition for your operations.