Security migration guide

Migrate from Legacy AccessCode Authentication to JWT Authentication

This guide explains how to migrate existing VINquery API integrations from the legacy AccessCode authentication model to JWT Bearer authentication. The migration is designed to minimize changes to your existing applications.

VINdecode API VINfix API VINocr API VINbarcode API DecisioQ API

1. The Most Important Thing to Know

Only the authentication mechanism changes. Your existing API endpoints, request parameters, request JSON, response JSON, and business logic remain unchanged.

2. APIs Covered

The following VINquery APIs are covered by this guide:

VINdecode API

VINfix API

VINocr API

VINbarcode API

3. What Changes

AccessCode authentication is replaced with JWT Bearer authentication.
Your backend requests JWT access tokens from https://identity.vinquery.com/connect/token.
Each API request includes an Authorization: Bearer header.
The ClientSecret must remain on your backend.

4. What Does NOT Change

API endpoints
Query string parameters
Request payloads
Response payloads
Business logic
Application workflow

5. Migration Overview

Create an API Consumer.
Verify the ClientId and ClientSecret.
Update your backend to request JWT access tokens.
Replace AccessCode authentication with JWT Bearer authentication.
Test your existing integration.
Deploy to production.

6. Step 1 - Create an API Consumer

Sign in to the VINquery Portal, open My API Consumers, click Create API Consumer, enter a descriptive name, select the appropriate API audience, and save.

The portal generates a ClientId and ClientSecret. The ClientSecret is displayed only once, so store it securely.

7. Step 2 - Verify Your ClientId and ClientSecret

Before updating your application, verify that your credentials can successfully obtain a JWT access token.

Copy the PowerShell script below into Notepad, replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your own values, then copy and paste the updated script into a Windows PowerShell window and press Enter to run it.

# Replace these values with your own credentials
$clientId = "YOUR_CLIENT_ID"
$clientSecret = "YOUR_CLIENT_SECRET"

$tokenResponse = Invoke-RestMethod `
  -Method Post `
  -Uri "https://identity.vinquery.com/connect/token" `
  -ContentType "application/json" `
  -Body (@{
    clientId = $clientId
    clientSecret = $clientSecret
    audience = "vinquery:api:vindecode"
  } | ConvertTo-Json)

$tokenResponse.jwtToken

Expected Result

If the request succeeds, PowerShell will display the JSON response followed by the JWT access token. Receiving an access_token confirms that your ClientId and ClientSecret are valid and ready to use in your application.

8. Step 3 - Update Your Backend

Store the ClientSecret securely on your backend, request and cache JWT access tokens, and include the Authorization Bearer header when calling VINquery APIs.

9. Step 4 - Replace AccessCode Authentication

Before

GET /api/...?...&AccessCode=YOUR_ACCESS_CODE

After

Authorization: Bearer <jwt-token>

10. Do I Need a Server-side Proxy?

If your application already communicates with VINquery APIs through your own backend, you normally only need to update your authentication logic.

If your application currently calls VINquery APIs directly from browser JavaScript or another client-side application, introduce a server-side proxy to securely store the ClientSecret, request JWTs, call the VINquery APIs, and return the responses.

11. Protect Your ClientSecret

Store it only on your backend.
Never expose it in browser JavaScript.
Never embed it in mobile applications.
Never commit it to source control.
Rotate it immediately if compromised.

12. API Audience Reference

VINquery API	JWT Audience
VINdecode API	`vinquery:api:vindecode`
VINfix API	`vinquery:api:vinfix`
VINocr API	`vinquery:api:vinocr`
VINbarcode API	`vinquery:api:vinbarcode`

13. Troubleshooting

Issue	Possible Cause
400 Bad Request	Malformed request.
401 Unauthorized	Missing or expired JWT.
403 Forbidden	Incorrect audience or insufficient permissions.
415 Unsupported Media Type	Content-Type does not match the token endpoint. Use `application/json`.
invalid_client	ClientId or ClientSecret is incorrect.

14. Frequently Asked Questions

Do I need to rewrite my integration?

No. Only the authentication mechanism changes.

Do API endpoints change?

No.

Do request or response JSON change?

No.

Can I continue using AccessCode?

No. Migrate to JWT authentication before the retirement date.

15. Migration Checklist

Create an API Consumer
Record the ClientId and ClientSecret
Verify credentials using the PowerShell test
Update backend authentication
Replace AccessCode with JWT
Test all VINquery API calls
Deploy to production