OAuth 2.0 Integration Guide
Introduction To OAuth 2.0
OAuth 2.0 is a security protocol that allows applications to access API resources securely using tokens instead of sensitive credentials like usernames and passwords. Follow this guide to implement OAuth 2.0 for your interactions with DSV’s public APIs. Here is everything you need to know about obtaining tokens, using them, refreshing them, and troubleshooting
Overview of the OAuth workflow
1. Register with DSV: Make sure you have myDSV credentials (username & password).
2. Obtain Tokens: Use your myDSV credentials and DSV-Subscription-Key to request an access token and refresh token from the token endpoint.
3. Access API Resources: Include the access token in the header of your API requests for secure access to DSV resources.
4. Refresh Tokens: Renew your access token with the refresh token when it expires, ensuring uninterrupted access.
Step 1: Obtaining Access Token
To start, you will need an access token. The access token gives you short-term access to the APIs, while the refresh token allows you to renew access without re-authenticating.
1. Prepare Your Credentials:
Verify your MyDSV Access
Your MyDSV username and password will be required to initiate the authentication process. These credentials are necessary as part of your body request for authentication.
Subscribe to the API “DSV Access Token”
In addition to subscribing to the specific Generic API you plan to use; you must also subscribe to the DSV Access Token API. This subscription is required to obtain the bearer token for OAuth 2.0 authentication.
Add your subscription key to the request header.
You can locate this DSV-Subscription-Key in your profile on the Developer Portal.
2. Request the Token:
Send a POST request to the appropriate token endpoint (either production or demo).
Include your myDSV credentials in the body request.
Add your DSV-Subscription-Key in the header.
Token Endpoint:
API Development Environment
URL Endpoint
Demo
Production
Example Request:
Body Request (Application x--www-form-urlencoded):
client_id={myDSV User}&client_secret={myDSV Password}&grant_type=client_credentials
These credentials are used to authenticate the client and retrieve an access token. Ensure the Content-Type header is set to application/x-www-form-urlencoded to avoid request errors.
Example Response
access_token: Grants access to API resources for 10 minutes.
refresh_token: Allows you to request a new access token for 30 days.
Step 2: Using The Access Token
Once you have an access token, you will need to include it in the header of your API requests. Format the header as shown:
Authorization Header:
Authorization: Bearer {access_token}
This access token grants secure, temporary access to protected resources. Always use HTTPS to prevent unauthorized access, as tokens contain sensitive information.
Step 3: Refresh the Access Token
To maintain access, renew your access token before it expires. You can do this by submitting the refresh token, which avoids requiring users to re-authenticate fully.
Prepare the Request:
Send a POST request to the token endpoint with grant_type set to refresh_token.
Include the latest refresh token and your client credentials in the request.
Example Request:
Set the “Refresh token” you obtained from your previous call into your body request:
grant_type=refresh_token&refresh_token={your_refresh_token}
Example Response:
When your refresh token expires after 30 days you will need to authenticate again with the username and password to obtain new tokens.
Best Practices
Store Tokens Securely: Do not expose tokens in URLs, logs, or any publicly accessible places.
Regular Token Rotation: Regularly refresh tokens to prevent unauthorized access. Monitor token usage and rotate tokens periodically for added security.
Error Handling: Set up checks for 401 Unauthorized responses. These usually indicate an expired or invalid token, and refreshing the token will resolve this in most cases.
Troubleshooting And Common Errors
If you encounter errors, here are some common ones and tips on resolving them:
401 Unauthorized: This error often means your access token has expired. Use your refresh token to obtain a new one.
403 Forbidden: This may indicate invalid credentials or insufficient permissions. Double-check your credentials and access scopes.
Invalid Token Format: Ensure the token follows the correct format (Bearer {token}). If you are copying the token manually, verify it is complete.
Expired Refresh Token: If the refresh token expires, you will need to log in again with your username and password to request a new one.
FAQ: OAuth 2.0 Integration with DSV Public APIs
1. Why Is OAuth 2.0 Required for Accessing DSV APIs?
OAuth 2.0 ensures secure, scalable, and efficient interactions with DSV’s APIs, protecting sensitive data while enabling streamlined access for business-critical applications.
2. What is the impact of token expiration on my application?
If not managed properly, expired tokens can lead to failed API calls, disrupting workflows. Implement automated token refresh mechanisms to maintain seamless operations.
3. How can I prevent downtime due to token expiration?
Implement an automated token refresh system to renew access tokens before they expire, ensuring uninterrupted access to API resources.
4. What happens if my refresh token expires?
When your refresh token expires after 30 days, you will need to authenticate again using your username and password to obtain new tokens.
5. Can I automate token renewal?
Yes, it is recommended to automate the process of refreshing tokens before they expire to ensure uninterrupted access. Implement error handling to detect and respond to 401 errors by initiating a token refresh.
Contact Us
Our support team is here to help with any questions regarding OAuth 2.0 or integration with DSV APIs. Reach out to us at developer.support@dsv.com for assistance at any time.