The problem: one shared account, many applications

As companies grow, a single VinLink account is often used by more than one system. One application may decode VINs for a public website. Another may run nightly batch jobs. A mobile app may need vehicle data in the field. A development team may also need separate access for testing, staging, and production environments.

Using the same account email and password across all of these systems creates business and security problems:

• Too much shared access. Every application depends on the same login credentials.
• Harder troubleshooting. If all traffic comes from one shared login, it is difficult to identify which app, client, or environment caused a problem.
• Difficult rotation. Changing the account password can break every integration at once.
• Risk from employee or vendor changes. When a contractor, developer, or client no longer needs access, removing their access may require changing credentials for everyone.
• Limited control over usage. Different applications may need different report types, IP restrictions, or expiration rules.

For a single user logging in through the VinLink website, a password is simple and appropriate. For multiple applications, clients, or automated workflows, a shared password is not the best operational model.

The solution: create a separate API key for each use case

VinLink API keys allow your account to issue independent credentials for different applications, clients, services, environments, or automation workflows. Instead of embedding your account password in an application, you create an API key for that application.

Each key can be named, managed, restricted, revoked, or rotated without changing your main account password and without affecting other integrations.

Use case	Recommended API key
Production website	Website production
Mobile application	Mobile app production
Nightly batch process	Batch decoder
Staging environment	Staging test key
External client integration	Client ABC integration
Internal developer testing	Developer sandbox

Why API keys matter for business users

How VinLink API key authentication works

VinLink API keys work together with JWT authentication. The API key is not sent directly to vehicle report endpoints. Instead, the application first exchanges the API key for a standard JWT token. The application then uses that JWT token when calling the VinLink API.

1. Create an API key under your VinLink account.
2. Store the full API key securely.
3. Exchange the API key for a JWT access token.
4. Call VinLink API endpoints using Authorization: Bearer <accessToken>.
5. Refresh the token when needed.
6. Rotate or revoke the API key when access should change.

API keys provide independent access management, while VinLink continues using JWT Bearer tokens for API calls.

Recommended API key strategy

For most organizations, the best practice is to create one API key per application, client, environment, or automation workflow. Avoid using one key everywhere. A single shared API key recreates many of the same problems as a shared password.

Security controls available for API keys

Control	How it helps
Scopes	Scopes define what the key is allowed to do. For report access, use the REPORT scope.
Report type restrictions	A key can be limited to specific report types, such as BASIC or BASIC_PLUS.
Expiration date	Expiration dates are useful for temporary vendors, test projects, pilots, or short-term integrations.
IP whitelist	Keys can be restricted to specific IP addresses or CIDR ranges, which is especially useful for server-side applications.
Revocation	A key can be revoked when it is no longer needed. Revocation is immediate and permanent.
Rotation	A key secret can be rotated. Rotation creates a new secret for the same key identity and invalidates the old secret immediately.

Common business scenarios

---

Developer quick start

API key format

VinLink API keys use this format:

vk_{publicId}_{secret}

The publicId identifies the key for management operations. The secret portion is shown only once when the key is created. Store it securely immediately.

Step 1: Create an API key

Creating an API key requires an account JWT obtained through normal password login.

TOKEN=$(curl -s -X POST https://api.vinlink.com/user/login \
  -H "Content-Type: application/json" \
  -d '{"login":"your@email.com","password":"yourpassword"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['accessToken'])")

curl -X POST https://api.vinlink.com/user/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Production App",
    "description": "Production server integration",
    "scopes": ["REPORT"],
    "reportTypes": ["BASIC", "BASIC_PLUS"],
    "expiresAt": null,
    "ipWhitelist": null
  }'

The response includes fullApiKey. Save it immediately. It is shown only once.

Step 2: Exchange the API key for a JWT

curl -X POST https://api.vinlink.com/auth/api-key/token \
  -H "Authorization: ApiKey vk_a1b2c3d4_s3cr3tpart"

The response returns a standard token payload:

{
  "accessToken": "eyJhbGci...",
  "refreshToken": "eyJhbGci...",
  "tokenType": "Bearer",
  "expiresIn": 3600
}

Step 3: Call the VinLink API with the JWT

Use the access token exactly like a password-login JWT:

curl "https://api.vinlink.com/report/v1/report/BASIC?vin=1HGBH41JXMN109186" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Step 4: Refresh the JWT when needed

curl -X POST https://api.vinlink.com/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "eyJhbGci..."}'

Managing API keys

API key management requires your account JWT. The API key itself cannot be used to manage keys.

List keys

curl https://api.vinlink.com/user/api-keys \
  -H "Authorization: Bearer $TOKEN"

Revoke a key

curl -X DELETE https://api.vinlink.com/user/api-keys/{publicId} \
  -H "Authorization: Bearer $TOKEN"

Rotate a key secret

curl -X POST https://api.vinlink.com/user/api-keys/{publicId}/rotate \
  -H "Authorization: Bearer $TOKEN"

The new full API key is shown only once. Store it securely and update the application that uses it.

Best practices for VinLink API keys

• Create one key per application, client, environment, or workflow.
• Do not share one key across unrelated systems.
• Use clear names and descriptions.
• Restrict report types when an application does not need full access.
• Use IP restrictions for server-side integrations when possible.
• Store API keys in a secure secret manager or protected environment variable.
• Never commit API keys to source code.
• Rotate keys periodically or when staff, vendors, or deployment environments change.
• Revoke keys immediately when they are no longer needed.
• Use account login only for account management and API key administration.

Frequently asked questions

Are API keys a replacement for JWT tokens?

No. VinLink API keys are used to obtain JWT tokens. API requests still use JWT Bearer authentication.

Should I put my VinLink account password in my application?

No. For applications, integrations, mobile clients, and automation workflows, use API keys instead of embedding the account password.

Can I disable one application without changing my password?

Yes. Revoke the API key used by that application.

Can different clients or applications have different access?

Yes. Create separate API keys and configure each key for the required purpose, scope, report types, expiration, or IP restrictions.

What happens if an API key is lost?

The secret cannot be recovered. Revoke the old key and create or rotate a new one.

Can an API key manage other API keys?

No. API key management requires account authentication. API keys are used for application access, not account administration.