> ## Documentation Index
> Fetch the complete documentation index at: https://smartcar.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# API Authentication Setup
> Set up API Authentication to access the Smartcar API using application-level tokens.
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
In your [Smartcar Dashboard](https://dashboard.smartcar.com), go to your application and select the **API Credentials** tab.
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.
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](/connect/handle-the-response).
***
## Step 3: Obtain an Access Token
Exchange your API credentials for an access token using the client credentials grant:
```bash cURL theme={null}
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"
```
```javascript Node.js theme={null}
const response = await fetch('https://iam.smartcar.com/oauth2/token', {
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
},
body: new URLSearchParams({
grant_type: 'client_credentials',
client_id: process.env.SMARTCAR_CLIENT_ID,
client_secret: process.env.SMARTCAR_CLIENT_SECRET,
}),
});
const { access_token, expires_in } = await response.json();
```
```python Python theme={null}
import requests
import os
response = requests.post(
'https://iam.smartcar.com/oauth2/token',
data={
'grant_type': 'client_credentials',
'client_id': os.environ['SMARTCAR_CLIENT_ID'],
'client_secret': os.environ['SMARTCAR_CLIENT_SECRET'],
}
)
token_data = response.json()
access_token = token_data['access_token']
```
**Response:**
```json theme={null}
{
"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:
```bash cURL theme={null}
curl -X GET "https://vehicle.api.smartcar.com/v3/vehicles/{vehicleId}" \
-H "Authorization: Bearer {access_token}"
```
```javascript Node.js theme={null}
const response = await fetch(
`https://vehicle.api.smartcar.com/v3/vehicles/${vehicleId}`,
{
headers: {
'Authorization': `Bearer ${accessToken}`,
},
}
);
```
```python Python theme={null}
import requests
response = requests.get(
f'https://vehicle.api.smartcar.com/v3/vehicles/{vehicle_id}',
headers={
'Authorization': f'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](#step-2-capture-the-user-id-from-connect) above.
***
## Step 5: List User Connections
Use the Connections API to retrieve all vehicles connected by a specific user:
```bash theme={null}
curl -X GET "https://vehicle.api.smartcar.com/v3/connections?filter[user_id]={userId}" \
-H "Authorization: Bearer {access_token}"
```
**Response:**
```json theme={null}
{
"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:
```json theme={null}
{
"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
* [Overview](/api-reference/authorization/overview) — Understand when and why to use API Authentication
* [Migration Guide](/getting-started/how-to/m2m/migration-guide) — Transition from per-vehicle tokens
* [FAQ](/getting-started/how-to/m2m/faq) — Common questions and answers
* [Connections API Reference](/api-reference/list-connections) — List and manage connections
* [Webhooks Overview](/integrations/webhooks/overview) — Set up event-driven updates