API Request Authentication

How do I authenticate my requests?

To ensure secure access to the Enterprise API, we utilize a combination of OAuth2 and subscription keys.

These mechanisms work together to authenticate and authorize API requests, safeguarding your data and ensuring that only authorized users can access the API.

OAuth2 Authentication

Each customer is provided with unique credentials, including a client ID (sent by E-mail) and client secret (sent by SMS), upon onboarding.
To authenticate, clients must first obtain an access token by making a request to our token endpoint using their credentials.
This access token is then included in the Authorization header (Authorization: Bearer <access_token>) of each API request.
The token is only valid for 5 minutes, after which it expires and must be requested again.

Subscription Key

In addition to the token, a subscription key is required to authorize access to specific API resources.
The subscription key, which is issued during the onboarding process and sent by onboarding E-mail, must be included in the Ocp-Apim-Subscription-Key header of each API request.
This key helps us manage and monitor API usage, ensuring that requests are coming from valid and authorized subscriptions.
Subscriptions are issued only once and do not expire

Security Note

Ensure that both your credentials and subscription key are stored securely and not exposed in client-side code.

How do I obtain an token?

To obtain a token, follow these steps:

1.Make a POST request to the token endpoint using your client credentials.

Token endpoint: https://my.dkv-mobility.com/auth/realms/enterprise-api/protocol/openid-connect/token

2.Include the following parameters in the request body:

grant_type: client_credentials

client_id: Your client ID (sent by E-Mail)

client_secret: Your client secret (sent by SMS)

scope: openId

Example Token Request:

curl -v -X POST https://my.dkv-mobility.com/auth/realms/enterprise-api/protocol/openid-connect/token \
      -H 'Content-Type: application/x-www-form-urlencoded' \
      -d 'grant_type=client_credentials' \
      -d 'client_id=[Your Unique client_id]' \
      -d 'client_secret=[Your Unique client_secret]' \
      -d 'scope=openid'

3.Receive the Token:

If your request is successful, you will receive a response containing the access token, which typically looks like this:

{
    "access_token": "<<CONTENT_OF_THE_JWT_TOKEN>>"
    "expires_in": 300,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "id_token": "<<CONTENT_OF_THE_ID_TOKEN>>"
    "not-before-policy": 0,
    "scope": "openid"
}

The access_token value is what you will use to authenticate your API requests.

4.Use the Token:

Include the access token in the Authorization header of your API requests.

Example API Request:

curl -v -X POST https://api.dkv-mobility.com/e-api/v2.0.0/transactions/transactionDate?size=100&page=0&customerId=0000123456&endDate=2024-05-30&startDate=2024-05-01\
     -H 'Authorization: bearer <<CONTENT_OF_THE_JWT_TOKEN>>'\
     -H 'Content-Type: application/json' \
     -H 'Content-Length: 0' \
     -H 'ocp-apim-subscription-key: <<CONTENT_OF_THE_SUBSCRIPTION_KEY>>'
     -H --data '{}' --compressed

5.Handle Token Expiry:

Tokens have an expiration time (expires_in), so you need to handle token renewal or re-authentication as needed.

Troubleshooting OAuth2 Errors

Verify Endpoint URL

Ensure you’re using the correct URL for the token endpoint. Check the API documentation for the precise endpoint and make sure there are no typos.

Check Request Headers

Make sure that the Content-Type header is set correctly to application/x-www-form-urlencoded.

Validate Credentials

Double-check that the client_id and client_secret you’re using are correct and active.

These values are case-sensitive and must match exactly what was provided during onboarding.Otherwise the authorization server denied the request

Review the error message returned by the server.

Common issues include:

Invalid Grant Type: Ensure grant_type is set to client_credentials.

Invalid Client ID/Secret: Verify the correctness of your credentials.

Missing or Invalid Parameters: Ensure all required parameters are included.

The authorization server could be temporarily unable to handle the request due to maintenance or other issues.

If the issue persists, contact the API Management Support team with detailed error information for assistance: api-management@dkv-mobility.com