> ## 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 FAQ

> Frequently asked questions about API Authentication and API credentials.

<AccordionGroup>
  ## General

  <Accordion title="What is API Authentication?">
    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.
  </Accordion>

  <Accordion title="How is API Authentication different from per-vehicle access tokens?">
    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.
  </Accordion>

  <Accordion title="Who can use API Authentication?">
    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.
  </Accordion>

  <Accordion title="Do I have to migrate to API Authentication?">
    No. There is no forced migration. Your existing opaque tokens continue to work indefinitely. You can adopt API Authentication at your own pace.
  </Accordion>

  ## Setup & Configuration

  <Accordion title="How do I create API credentials?">
    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.

    <Info>
      Store these credentials securely immediately after generation. The secret will not be displayed again.
    </Info>
  </Accordion>

  <Accordion title="Where do I find my client ID and secret?">
    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.
  </Accordion>

  <Accordion title="Can I have multiple API secrets?">
    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.

    <Tip>
      Use multiple secrets to support zero-downtime secret rotation. Generate a new secret, update your application to use it, then delete the old secret.
    </Tip>
  </Accordion>

  ## Authentication & Usage

  <Accordion title="How do I obtain an access token?">
    Send a POST request to the Smartcar token endpoint with your API credentials:

    ```bash theme={null}
    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.
  </Accordion>

  <Accordion title="How long are access tokens valid?">
    Access tokens are valid for 1 hour (3600 seconds). After expiration, you must request a new token using your API credentials.
  </Accordion>

  <Accordion title="Do access tokens have refresh tokens?">
    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.
  </Accordion>

  <Accordion title="What is the sc-user-id header?">
    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:

    ```bash theme={null}
    curl https://vehicle.api.smartcar.com/v3/vehicles \
      -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
      -H "sc-user-id: USER_ID"
    ```
  </Accordion>

  <Accordion title="How do I get a user's userId?">
    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.
  </Accordion>

  ## Migration

  <Accordion title="Can I use both API Authentication and opaque tokens at the same time?">
    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.
  </Accordion>

  <Accordion title="What happens to my existing opaque tokens if I enable API Authentication?">
    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.
  </Accordion>

  <Accordion title="Do I need to change my Connect flow?">
    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.
  </Accordion>

  <Accordion title="How do webhooks work with API Authentication?">
    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.
  </Accordion>

  ## Security

  <Accordion title="How should I store API credentials?">
    <Warning>
      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.
    </Warning>

    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
  </Accordion>

  <Accordion title="What happens if my client secret is compromised?">
    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.
  </Accordion>

  <Accordion title="Can an access token access any user's vehicles?">
    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.
  </Accordion>

  ## 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.
</AccordionGroup>