Skip to main content

​
General

API Authentication is an authentication method that uses the OAuth 2.0 Client Credentials flow. You exchange your API credentials for a short-lived access token and include the sc-user-id header in each request to specify which user’s vehicles you are accessing.
API Authentication is scoped to your application rather than to an individual vehicle. A single access token, combined with the sc-user-id header, lets you access any user’s vehicles connected to your application.
API Authentication is available for applications using Smartcar’s webhooks offering and the v3 REST API. If your application has not yet adopted the v3 API, you must upgrade first. Refer to the migration guide for steps.
No. There is no forced migration. Your existing opaque tokens continue to work indefinitely. You can adopt API Authentication at your own pace.

​
Setup & Configuration

You create API credentials through the Smartcar Dashboard. Navigate to the API Credentials tab in your application settings and click Create Secret. The dashboard will provide you with a client ID and client secret.
Store these credentials securely immediately after generation. The secret will not be displayed again.
Your API credentials are available in the Smartcar Dashboard under the API Credentials tab. The client ID is always visible, but the client secret is only shown once at creation. If you lose the secret, you must generate a new one.
Yes. You can generate up to 3 client secrets for the same application. This is useful for credential rotation, allowing you to generate a new secret and retire the old one without downtime. Manage all secrets through the API Credentials tab in the Smartcar Dashboard.
Use multiple secrets to support zero-downtime secret rotation. Generate a new secret, update your application to use it, then delete the old secret.

​
Authentication & Usage

Send a POST request to the Smartcar token endpoint with your API credentials:
curl -X POST https://iam.smartcar.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
The response includes an access_token that you use in subsequent API requests.
Access tokens are valid for 1 hour (3600 seconds). After expiration, you must request a new token using your API credentials.
No. Access tokens do not include refresh tokens. To obtain a new access token after expiration, simply make another request to the token endpoint with your API credentials. This ensures you always use fresh, short-lived tokens.
The sc-user-id header identifies which user’s vehicles you want to access. Since API credentials grant access to all vehicles connected to your application, this header scopes the request to a particular user. Include it in your API requests to ensure you only access the intended user’s vehicle data.Example:
curl https://vehicle.api.smartcar.com/v3/vehicles \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "sc-user-id: USER_ID"
The userId is returned in the Smartcar Connect flow after a user authorizes your application. You also receive it in webhook payloads under the user.id field. Store this identifier to use in the sc-user-id header for subsequent API requests on behalf of that user.

​
Migration

Yes. You can use application-level access tokens and opaque tokens simultaneously during your migration. This allows you to gradually transition your application without requiring all changes at once.
Your existing opaque tokens continue to work indefinitely. Enabling API Authentication does not affect or invalidate your current per-vehicle tokens. You can use both authentication methods concurrently.
No changes to your Connect flow are required. The Connect authorization flow remains the same. API credentials are generated separately through the dashboard and operate independently of the Connect flow.
Webhooks continue to function as before. Webhook payloads now include the user.id field nested inside the data object. Both Vehicle Connection Status and Vehicle State events contain the userId alongside the vehicleId. You can use this to identify which user’s vehicle triggered the event and use that userId in subsequent API requests with the sc-user-id header.

​
Security

Never store your client secret in public clients (frontend JavaScript, mobile apps) or in plain text files. Always store credentials securely on your backend server using environment variables or a secure secrets management system.
Best practices:
  • Store credentials in environment variables or a secrets vault
  • Use infrastructure-level security (IAM roles, key management services)
  • Never commit credentials to version control
  • Rotate secrets regularly according to your security policy
If you suspect your client secret has been compromised:
  1. Generate a new API credential immediately through the Smartcar Dashboard
  2. Update your application to use the new secret
  3. Delete the compromised secret
  4. Review your audit trail for any unauthorized access
All token requests are logged, so you can check your audit trail to identify any suspicious activity.
Access tokens grant access to all vehicles connected to your application. However, you control which user’s vehicles you access by specifying the sc-user-id header in each request. Only vehicles connected to that specific user are accessible. Always verify you’re using the correct userId to prevent unauthorized access to other users’ data.

​
Still Have Questions?

If you need additional help with API Authentication, reach out to the Smartcar support team. Our team is here to help you implement it securely and efficiently.