[← API v2 Overview](https://motordesk.com/api-docs/v2/)

# 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**](https://my.motordesk.com/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:

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

```php
// 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();
```

```python
import requests

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

```javascript
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](https://motordesk.com/api-docs/v2/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

> ** There is currently no sandbox. The API acts on live data and can send customer-facing email (assuming email is set-up), reset passwords, create leads and delete records. To test safely, sign up for a **free trial account** (business verification required) and issue a key there, kept separate from your live account. If you already have a live account, [**contact support**](https://my.motordesk.com/support/) and we can add a separate **developer account** you can switch to from the same login.

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

| Scope | Grants |
| --- | --- |
| `meta:read` | Read API metadata and endpoint catalogue. |

### Reference

| Scope | Grants |
| --- | --- |
| `reference:read` | Read reference lists. |

### Business

| Scope | Grants |
| --- | --- |
| `business:read` | Read the business profile (contact details, address, localisation and opening hours). |

### Webhooks

| Scope | Grants |
| --- | --- |
| `webhooks:read` | Read webhook subscriptions and their deliveries. |
| `webhooks:write` | Create, update, delete, ping and manage webhook subscriptions. |

### Contacts

| Scope | Grants |
| --- | --- |
| `contacts:read` | Read contacts. |
| `contacts:write` | Create and update contacts. |
| `contacts:delete` | Delete contacts. |

### Contact Notes

| Scope | Grants |
| --- | --- |
| `contact-notes:read` | Read contact notes. |
| `contact-notes:write` | Add contact notes. |
| `contact-notes:delete` | Delete contact notes. |

### Contact Login

| Scope | Grants |
| --- | --- |
| `contact-login:write` | Reset and email contact login details. |

### Leads

| Scope | Grants |
| --- | --- |
| `leads:read` | Read leads. |
| `leads:write` | Create and update leads. |
| `leads:delete` | Delete leads. |

### Lead Vehicles

| Scope | Grants |
| --- | --- |
| `lead-vehicles:read` | Read lead vehicle associations. |
| `lead-vehicles:write` | Create lead vehicle associations. |
| `lead-vehicles:delete` | Delete lead vehicle associations. |

### Lead Messages

| Scope | Grants |
| --- | --- |
| `lead-messages:read` | Read lead messages. |
| `lead-messages:write` | Create, update, and send lead messages. |
| `lead-messages:delete` | Delete lead messages. |

### Lead Notes

| Scope | Grants |
| --- | --- |
| `lead-notes:read` | Read lead notes. |
| `lead-notes:write` | Add lead notes. |
| `lead-notes:delete` | Delete lead notes. |

### Lead Appointments

| Scope | Grants |
| --- | --- |
| `lead-appointments:read` | Read lead appointments. |
| `lead-appointments:write` | Create lead appointments. |
| `lead-appointments:delete` | Delete lead appointments. |

### Appointments

| Scope | Grants |
| --- | --- |
| `appointments:read` | Read appointments and calendars. |
| `appointments:write` | Create and update appointments and calendars. |
| `appointments:delete` | Delete appointments. |

### Calls

| Scope | Grants |
| --- | --- |
| `calls:read` | Read VOIP call logs. |
| `calls:write` | Create and update VOIP call logs. |

### Blog Articles

| Scope | Grants |
| --- | --- |
| `blogs:read` | Read website blog articles. |
| `blogs:write` | Create and update website blog articles. |
| `blogs:delete` | Delete website blog articles. |

### Reviews

| Scope | Grants |
| --- | --- |
| `reviews:read` | Read customer reviews. |
| `reviews:write` | Create, update and approve customer reviews. |
| `reviews:delete` | Delete customer reviews. |

### Deals

| Scope | Grants |
| --- | --- |
| `deals:read` | Read deals. |

### Listings

| Scope | Grants |
| --- | --- |
| `listings:read` | Read public listings (advert data only - no business, cost or customer data). |

### Invoices

| Scope | Grants |
| --- | --- |
| `invoices:read` | Read invoices. |
| `invoices:write` | Create, edit, issue and cancel invoices. |
| `invoices:payment` | Record invoice payments (mark paid). |
| `invoices:credit` | Raise and remove invoice credit notes. |
| `invoices:delete` | Delete draft invoices. |

### Orders

| Scope | Grants |
| --- | --- |
| `orders:read` | Read orders. |
| `orders:write` | Create, edit, issue, cancel and convert orders. |
| `orders:delete` | Delete draft orders. |

### Purchases

| Scope | Grants |
| --- | --- |
| `purchases:read` | Read purchases. |
| `purchases:write` | Create, edit, issue and cancel purchases. |
| `purchases:payment` | Record purchase payments. |
| `purchases:credit` | Raise and remove purchase credit notes. |
| `purchases:delete` | Delete draft purchases. |

### Documents

| Scope | Grants |
| --- | --- |
| `documents:read` | Read document templates. |
| `documents:send` | Send documents. |

### Document Signatures

| Scope | Grants |
| --- | --- |
| `document-signatures:read` | Read document signature requests. |

### Vehicle Lookups

| Scope | Grants |
| --- | --- |
| `vehicle-lookups:write` | Run vehicle lookups. |

### Vehicle Recognitions

| Scope | Grants |
| --- | --- |
| `vehicle-recognitions:write` | Recognise registrations and VINs. |

### Vehicle Taxonomy

| Scope | Grants |
| --- | --- |
| `vehicle-taxonomy:read` | Read vehicle taxonomy values. |

### Vehicles

| Scope | Grants |
| --- | --- |
| `vehicles:read` | Read vehicles. |
| `vehicles:write` | Create and update vehicles (including status changes). |
| `vehicles:delete` | Delete vehicles. |

### Vehicle Pricing

| Scope | Grants |
| --- | --- |
| `vehicle-pricing:read` | Read vehicle pricing and valuations. |

### Vehicle Lookup

| Scope | Grants |
| --- | --- |
| `vehicle-lookup:read` | Read third-party vehicle lookup data (DVLA, DVSA, AutoTrader check). |

### Vehicle Competitors

| Scope | Grants |
| --- | --- |
| `vehicle-competitors:read` | Read vehicle competitor data. |

### Vehicle Media

| Scope | Grants |
| --- | --- |
| `vehicle-media:read` | Read vehicle media. |
| `vehicle-media:write` | Attach vehicle media. |
| `vehicle-media:delete` | Delete vehicle media. |

### Vehicle Test Drives

| Scope | Grants |
| --- | --- |
| `vehicle-drives:read` | Read vehicle test drives. |
| `vehicle-drives:write` | Start, end, sign and record vehicle test drives. |

### Vehicle Reservations

| Scope | Grants |
| --- | --- |
| `vehicle-reserve:read` | Read vehicle reservations. |
| `vehicle-reserve:write` | Reserve and cancel vehicle reservations. |

### Vehicle Appraisals

| Scope | Grants |
| --- | --- |
| `vehicle-appraisals:write` | Drive the appraisal offer workflow (request, confirm, accept, decline, reopen). |

### Vehicle Documents

| Scope | Grants |
| --- | --- |
| `vehicle-documents:read` | Read and download vehicle documents. |
| `vehicle-documents:write` | Upload and update vehicle documents. |
| `vehicle-documents:delete` | Delete vehicle documents. |

### Vehicle Job Boards

| Scope | Grants |
| --- | --- |
| `vehicle-jobs:read` | Read vehicle job boards (stages, tasks, notes, clocking, documents, purchases). |
| `vehicle-jobs:write` | Apply job boards and edit their stages, tasks, notes, clocking, documents and purchases. |
| `vehicle-jobs:delete` | Remove vehicle job boards and their stages, tasks, notes, clocking and uploads. |

### Vehicle Descriptions

| Scope | Grants |
| --- | --- |
| `vehicle-descriptions:write` | Generate vehicle advert text. |

### Search

| Scope | Grants |
| --- | --- |
| `search:wildcard` | Use wildcard filters where supported. |