← API v2 Overview

Authentication & API Keys

Every request authenticates with a per-business API key sent as a bearer token. Keys carry a fixed set of scopes that determine which endpoints they may call.

Getting a Key

API keys are created and managed inside MotorDesk under Business → API. There is no self-serve developer portal; a business user with access to that page issues keys for their own account.

When you create a key you:

• Give it a name (so usage can be identified later).
• Choose its scopes from the grouped picker: a key only has the scopes selected at creation. Grant the minimum the integration needs.

The secret is shown once, at creation. Store it securely; it cannot be retrieved again. The same page lists each key's last-used time and lets you revoke a key immediately. To rotate, create a new key, migrate your integration to it, then revoke the old one.

Using the Token

A credential is a key id and secret joined by a dot (key_id.secret). Send it as a bearer token on every request:

curl https://api.motordesk.com/2.0/contacts \
  -H "Authorization: Bearer key_id.secret"

// composer require motordesk/api2
use MotorDesk\Api2\Client;

// The SDK reads the same key_id.secret and sends the bearer header for you.
$client = new Client(apiKey: 'key_id.secret');
$contacts = $client->contacts()->list();

import requests

resp = requests.get(
    "https://api.motordesk.com/2.0/contacts",
    headers={"Authorization": "Bearer key_id.secret"},
)
resp.raise_for_status()

const res = await fetch("https://api.motordesk.com/2.0/contacts", {
  headers: { Authorization: "Bearer key_id.secret" },
});

Authentication failures return 401 (authentication_required, authentication_invalid, authentication_expired, authentication_revoked); a key that authenticates but lacks the required scope returns 403 (scope_denied / scope_required). A frozen or suspended business is locked out of the API entirely, returning 403 (account_frozen / account_suspended) until the account is restored. See Errors.

API access requires the Growth plan or above; it is not available on the Starter plan, on read-only accounts, or on demo accounts. Requests from an ineligible account return 403 (plan_upgrade_required, account_read_only or account_demo).

API 2.0 must also be enabled for the business. Access is requested from the dashboard and granted by our team; until then, and if access is later withdrawn, requests return 403 (api_access_required) even with a valid key.

Cross-Origin (CORS)

The API sends permissive CORS headers and answers preflight OPTIONS requests automatically, so it can be called directly from browser-based tools. Because the bearer secret must stay private, only use it from a browser in trusted, internal contexts - never embed a key in public, client-side code shipped to end users.

Testing Safely

Discovering a Key's Access

GET /2.0/meta returns the endpoint catalogue available to the calling key, so you can confirm exactly which endpoints and scopes a credential can use before building against them.

Scope Catalogue

The full set of scopes that can be granted to a key. Each endpoint's reference lists the single scope it requires.

Meta

Reference

Business

Webhooks

Contacts

Contact Notes

Contact Login

Leads

Lead Vehicles

Lead Messages

Lead Notes

Lead Appointments

Appointments

Calls

Blog Articles

Reviews

Deals

Listings

Invoices

Orders

Purchases

Documents

Document Signatures

Vehicle Lookups

Vehicle Recognitions

Vehicle Taxonomy

Vehicles

Vehicle Pricing

Vehicle Lookup

Vehicle Competitors

Vehicle Media

Vehicle Test Drives

Vehicle Reservations

Vehicle Appraisals

Vehicle Documents

Vehicle Job Boards

Vehicle Descriptions

Search