Migrate from Legacy AccessCode Authentication to JWT Authentication

1. The Most Important Thing to Know

2. APIs Covered

The following VINquery APIs are covered by this guide:

5. Migration Overview

1. Create an API Consumer.
2. Verify the ClientId and ClientSecret.
3. Update your backend to request JWT access tokens.
4. Replace AccessCode authentication with JWT Bearer authentication.
5. Update the API URL if the integration still uses a legacy endpoint.
6. Test your existing integration.
7. Deploy to production.

Top 5 Migration Mistakes

Check these items first when a migrated integration cannot authenticate.

1. Using the legacy API endpoint

Why it happens: The token request succeeds, so the existing service URL is assumed to support JWT. JWT authentication works only with JWT-enabled API endpoints; obtaining a JWT does not make an older endpoint capable of authenticating it.

How to recognize it: The API may return a historical message such as Service access denied: Double check your Access Code., even though the request is intended to use JWT.

How to fix it: Compare the configured API URL with the current endpoint documented for that API and route the request to the JWT-enabled endpoint. See JWT Migration FAQs for endpoint checks.

2. Forgetting the Authorization header

Why it happens: The application obtains a token but does not attach it to subsequent API calls. Generating a JWT alone is insufficient.

How to recognize it: Identity Service returns a token successfully, but the API request is unauthorized.

How to fix it: Include this header on every API request:

Authorization: Bearer <JWT>

3. Continuing to send the accessCode parameter

Why it happens: Legacy request construction remains in place while JWT support is added.

How to recognize it: The request contains both an Authorization header and an accessCode query-string or payload value.

How to fix it: Remove the accessCode parameter. JWT completely replaces Access Code authentication; do not send both unless VINquery specifically instructs you to do so.

4. Authorization header not reaching the API

Why it happens: Reverse proxies, API gateways, IIS, web servers, firewalls, load balancers, or application frameworks may strip or fail to forward Authorization headers.

How to recognize it: The client shows the header, but the destination API behaves as though no JWT was supplied.

How to fix it: Inspect the outgoing request and each infrastructure hop with browser developer tools, the Postman Console, Fiddler, or another HTTP inspection tool. Confirm that the API ultimately receives the header.

5. Using an expired or invalid JWT

Why it happens: A cached token expires, the token is malformed, or it was signed or issued for the wrong configuration.

How to recognize it: A previously working request begins returning an authentication failure, or a freshly pasted token is rejected.

How to fix it: Generate a fresh JWT, verify its expiration time and audience, and send the token exactly as returned by Identity Service.

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.

# 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

    # IMPORTANT:
    # Replace the audience below with the Allowed API / JWT Audience
    # configured for your API Consumer in the VINquery portal.
    # Examples:
    #   vinquery:api:vindecode
    #   vinquery:api:vinfix
    #   vinquery:api:vinocr
    #   vinquery:api:vinbarcode
    #   vinquery:api:decisioq
    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; it does not confirm that a later API request uses the correct endpoint or sends the token. If that request fails, review the Top 5 Migration Mistakes and JWT Migration FAQs.

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. If a header is present in application code but authentication still fails, see Authorization header not reaching the API and the JWT Migration FAQs.

9. Step 4 - Replace AccessCode Authentication

Before

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

After

Authorization: Bearer <jwt-token>

Remove the accessCode parameter and confirm that the request targets the current JWT-enabled API endpoint. See Top 5 Migration Mistakes for common request-update problems.

10. Do I Need a Server-side Proxy?

Yes. A server-side proxy is required because the API Consumer Client Secret must remain secure. JWT bearer tokens must be requested and managed by trusted server-side code. Browser JavaScript, HTML, desktop clients, and mobile apps must never contain the Client Secret. All VINquery API requests should be made through your server-side proxy.

Learn how to build a Server-Side Proxy →

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

13. Troubleshooting

14. JWT Migration FAQs

I successfully generated a JWT, but the API still says: “Service access denied: Double check your Access Code.”

This does not necessarily mean an Access Code is still required. The most common causes are a legacy API endpoint, a missing Authorization header, an Authorization header stripped before reaching the API, or an invalid or expired JWT. Verify these items before assuming Access Code authentication is still required.

Which API endpoint should I use with JWT authentication?

JWT authentication works only with JWT-enabled API endpoints. Update the application to use the current endpoint documented in this migration guide and in the documentation for the selected VINquery API. Using an older endpoint may produce legacy Access Code errors.

Should I continue sending my Access Code together with my JWT?

No. JWT completely replaces Access Code authentication. Remove the accessCode parameter from requests and do not send both authentication methods unless VINquery specifically instructs you to do so.

I removed the Access Code, but the service still behaves like it expects one.

The request may be using an old endpoint, may be routed to a legacy server, may be missing the Authorization header, or may pass through a proxy that removes the header. Verify the final destination URL and inspect the request at each infrastructure hop.

My JWT is generated successfully. Doesn't that mean authentication is working?

It confirms authentication with Identity Service, but API-request authentication is a separate step. Every API request must include:

Authorization: Bearer <JWT>

My VIN is null in the response.

Authentication and authorization checks often occur before VIN processing begins. A null VIN can therefore result from an authentication failure, authorization failure, malformed request, or missing VIN parameter. Verify authentication first, then confirm that the request uses the documented parameter name and format.

Can I continue using my Access Code while migrating?

Follow the migration and retirement policy stated in this guide and any customer-specific transition instructions supplied by VINquery. JWT should be used for all new development, and existing integrations should migrate before Access Code authentication is retired.

Besides authentication, what else changes?

In most cases, customers need only to generate a JWT, send the Authorization header, remove the Access Code, and update the API endpoint if the integration uses a legacy URL. Most business request parameters and response payloads remain unchanged.

How can I verify that my Authorization header is actually being sent?

Inspect the request with browser developer tools, the Postman Console, Fiddler, or another HTTP debugging tool. The outgoing API request should contain a header similar to:

Authorization: Bearer eyJ...

Can my web server remove the Authorization header?

Yes. Reverse proxies, API gateways, IIS configurations, load balancers, web servers, firewalls, and application frameworks sometimes strip or fail to forward Authorization headers. If the API never receives the JWT, authentication will fail.

How do I know whether I'm calling the legacy API or the JWT-enabled API?

Compare the application’s configured API URL with the current endpoint documented in this guide and the selected API’s documentation. Calling a legacy endpoint is one of the most common migration mistakes.

Why am I receiving an “Access Code” error when I'm no longer using Access Codes?

Some legacy services may still return historical error messages. The message does not necessarily mean an Access Code is required. Verify the endpoint, confirm that the Authorization header reaches the API, and generate a fresh valid JWT before concluding that the migration failed.

Do I need to rewrite my integration?

No. Authentication changes and the endpoint may need updating, but most request parameters, payloads, responses, business logic, and workflows remain unchanged.

Do API endpoints change?

They may. JWT must be sent to the current JWT-enabled endpoint; a legacy endpoint cannot authenticate a JWT merely because Identity Service issued one.

Do request or response JSON change?

Generally no. Remove any legacy accessCode value, but keep the business request and response contract unless the selected API documentation states otherwise.

Can I continue using AccessCode?

Migrate to JWT authentication before the retirement date and use JWT for all new development.

15. Migration Checklist

• Create an API Consumer
• Record the ClientId and ClientSecret
• Verify credentials using the PowerShell test
• Update backend authentication
• Use the current JWT-enabled API endpoint
• Include Authorization: Bearer <JWT> on every API request
• Remove the accessCode parameter
• Verify that proxies and gateways preserve the Authorization header
• Test all VINquery API calls
• Deploy to production