Skip to main content
API Authentication uses the OAuth 2.0 Client Credentials flow to obtain an application-level access token. Use this token to make API requests on behalf of your users.

​
Prerequisites

API Authentication is available for applications using Smartcar’s webhooks offering and the v3 REST API. If your application was created before June 1st, 2025, you may need to upgrade to the v3 API in your Dashboard settings.

​
Step 1: Generate Your API Credentials

1

Navigate to API Credentials

In your Smartcar Dashboard, go to your application and select the API Credentials tab.
2

Create an API Secret

Click Create Secret in the API Credentials section. Your client ID will be displayed, and a new client secret will be generated.
The client secret is only shown once. Copy and store it securely in your backend environment. Never expose API credentials in client-side code.
3

Store Credentials Securely

Store your API credentials in a secure secrets manager or environment variables. These credentials grant access to all vehicles connected to your application.

​
Step 2: Capture the User ID from Connect

When a user completes the Smartcar Connect flow, the redirect URL now includes a user_id parameter alongside the authorization code. Read more about Connect redirect url parameters here.

​
Step 3: Obtain an Access Token

Exchange your API credentials for an access token using the client credentials grant: 
curl -X POST "https://iam.smartcar.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"
Response: 
{
  "access_token": "{access_token}",
  "token_type": "Bearer",
  "expires_in": 3600
}
Access tokens are valid for 1 hour. There is no refresh token — simply request a new token when the current one expires.

​
Step 4: Make API Requests

Include the access token in the Authorization header: 
curl -X GET "https://vehicle.api.smartcar.com/v3/vehicles/{vehicleId}" \
  -H "Authorization: Bearer {access_token}"
When accessing vehicle signals or issuing commands, also include the sc-user-id header set to the user’s ID obtained from the Connect redirect. See Step 2 above.

​
Step 5: List User Connections

Use the Connections API to retrieve all vehicles connected by a specific user: 
curl -X GET "https://vehicle.api.smartcar.com/v3/connections?filter[user_id]={userId}" \
  -H "Authorization: Bearer {access_token}"
Response: 
{
  "connections": [
    {
      "id": "conn-uuid-1",
      "userId": "a4c82e9f-7b31-4d56-8e0a-3f6d91c5b2e7",
      "vehicleId": "vehicle-uuid-1",
      "connectedAt": "2025-01-15T10:30:00Z"
    },
    {
      "id": "conn-uuid-2",
      "userId": "a4c82e9f-7b31-4d56-8e0a-3f6d91c5b2e7",
      "vehicleId": "vehicle-uuid-2",
      "connectedAt": "2025-01-20T14:45:00Z"
    }
  ],
  "paging": {
    "cursor": null
  }
}

​
Security Best Practices

API credentials provide access to all vehicles connected to your application. Handle them with the same care as database credentials or encryption keys.
  • Never expose API credentials in client-side code (mobile apps, browser JavaScript, etc.)
  • Rotate secrets periodically using the Dashboard
  • Use environment variables or a secrets manager for credential storage
  • Implement audit logging for access token usage
  • Limit access to API credentials within your organization

​
Webhooks with API Authentication

When using API Authentication, webhook payloads include the user.id field nested inside the data object. Both Vehicle Connection Status and Vehicle State events contain the userId alongside the vehicleId, allowing you to identify which user’s vehicle triggered the event: 
{
  "eventId": "event-uuid",
  "eventType": "VEHICLE_STATE",
  "data": {
    "vehicle": {
      "id": "vehicle-uuid",
      "make": "Tesla",
      "model": "Model S",
      "year": 2020,
      "vin": "5YJSA1E26FFP12345"
    },
    "signals": [...],
    "user": {
      "id": "a4c82e9f-7b31-4d56-8e0a-3f6d91c5b2e7"
    }
  },
  "triggers": [...],
  "meta": {...}
}

​
What’s Next