API Key Management Guide

API Key Management Guide

Overview

This guide explains how to create, manage, and use API keys in the AutoElite system. API keys are used to authenticate requests to the AutoElite API from external applications.

API Key Types

AutoElite supports three types of API keys:

  1. Web Application Keys: For browser-based applications

    • Default permissions: Read-only access to vehicles
    • Example use case: Customer-facing website

  2. Desktop Application Keys: For desktop software

    • Default permissions: Read/write access to vehicles and dealers
    • Example use case: Inventory management software

  3. Mobile Application Keys: For mobile applications

    • Default permissions: Read access to vehicles and dealers
    • Example use case: Mobile app for salespeople

API Key Associations

API keys can be associated with:

  1. Dealer: The API key can only access data belonging to the specified dealer
  2. User: The API key inherits permissions from the specified user
  3. None: Super admin API keys with access to all data (restricted to system administrators)

Creating API Keys

From the Admin Portal

  1. Log in to the AutoElite Admin Portal

  2. Navigate to "API Keys" in the sidebar

  3. Click "Create API Key"

  4. Fill in the required information:

    • Name: A descriptive name for the API key
    • Description (optional): Additional details about the key's purpose
    • Application Type: Web, Desktop, or Mobile
    • Association: Select a dealer or user to associate with this key
    • Expiration Date (optional): When the key should expire

  5. Click "Create"

  6. Important: Copy the generated API key immediately. For security reasons, you won't be able to view the complete key again.

Via the API

POST /api/api-keys

Request Body:

{
  "name": "Downtown Dealer Website",
  "description": "API key for downtown dealer website",
  "app_type": "web",
  "app_id": "downtown-web",
  "dealer_id": 123
}

Response:

{
  "id": 1,
  "name": "Downtown Dealer Website",
  "description": "API key for downtown dealer website",
  "api_key": "autoelite-web-downtown-web-a1b2c3d4",
  "app_id": "downtown-web",
  "app_type": "web",
  "active": true,
  "created_at": "2023-11-15T16:30:00Z",
  "expires_at": null
}

Managing API Keys

Viewing API Keys

From the Admin Portal, you can view all API keys you have access to:

  • Super admins can see all API keys
  • Dealer admins can only see API keys associated with their dealer
  • Regular users can only see API keys associated with their account

Editing API Keys

You can edit the following properties of an API key:

  • Name
  • Description
  • Application type
  • Dealer/user association
  • Expiration date
  • Active status

Note: For security reasons, you cannot edit the actual API key string.

Revoking API Keys

To revoke an API key:

  1. Navigate to the API Keys page
  2. Find the API key you want to revoke
  3. Click the "Revoke" button
  4. Confirm the action

Once revoked, the API key can no longer be used to authenticate requests.

Using API Keys

In HTTP Requests

Include the API key in the X-API-Key header:

X-API-Key: autoelite-web-downtown-web-a1b2c3d4

For desktop applications, also include the application type:

X-App-Type: desktop

Example Request

GET https://api.autoelite.io/api/vehicles
Headers:
  X-API-Key: autoelite-web-downtown-web-a1b2c3d4
  Content-Type: application/json

Dealer-Specific Access Control

When an API key is associated with a specific dealer:

  1. Automatic Filtering: All vehicle queries are automatically filtered to only show vehicles belonging to that dealer
  2. Access Restrictions: Attempts to access vehicles from other dealers will be rejected with a 403 Forbidden error
  3. Automatic Assignment: New vehicles created with this API key will automatically be assigned to the associated dealer
  4. Update Restrictions: Updates to vehicles will be restricted to those belonging to the associated dealer

This ensures that each dealer can only access and modify their own data, even if they're using the same application.

Permissions Management

Default Permissions

Each API key type comes with default permissions:

  • Web: Read access to vehicles
  • Desktop: Read/write access to vehicles and dealers
  • Mobile: Read access to vehicles and dealers

Custom Permissions

You can customize permissions for each API key:

  1. Navigate to the API Keys page
  2. Find the API key you want to modify
  3. Click "Manage Permissions"
  4. Add or remove permissions as needed

Permissions are defined by:

  • Resource: The type of data (vehicles, dealers, users, etc.)
  • Action: The operation (read, write, delete)

Security Best Practices

  1. Treat API Keys as Secrets: Never expose API keys in client-side code or public repositories

  2. Use Appropriate Key Types: Use web application keys for browser-based applications, desktop keys for desktop applications, etc.

  3. Set Expiration Dates: For temporary access, set an expiration date on the API key

  4. Limit Permissions: Grant only the permissions necessary for the application to function

  5. Revoke Unused Keys: Regularly audit and revoke API keys that are no longer needed

  6. Rotate Keys Periodically: Create new API keys and phase out old ones on a regular schedule

  7. Monitor Usage: Keep track of API key usage and investigate any unusual patterns

Troubleshooting

401 Unauthorized Errors

If you're receiving 401 errors:

  • Verify the API key is correct
  • Check that the API key is active (not revoked)
  • Ensure the API key hasn't expired

403 Forbidden Errors

If you're receiving 403 errors:

  • Check if the API key has the necessary permissions
  • For dealer-specific API keys, ensure you're only accessing data for that dealer

Rate Limiting

If you're hitting rate limits:

  • Implement caching to reduce the number of API calls
  • Optimize your code to batch requests when possible
  • Consider upgrading to a higher tier if available