> ## Documentation Index
> Fetch the complete documentation index at: https://www.carstoragesoftware.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate every request with a team API key and grant only the scopes each integration needs.

Every request needs a team API key. Keys look like `csk_<prefix>.<secret>` and belong to exactly one team. A key can never read or change another facility's data.

## Send your key

Use either header. They are equivalent.

```bash Authorization header theme={null}
curl https://www.carstoragesoftware.com/api/v1/customers \
  -H "Authorization: Bearer csk_1a2b3c4d.your-secret"
```

```bash x-api-key header theme={null}
curl https://www.carstoragesoftware.com/api/v1/customers \
  -H "x-api-key: csk_1a2b3c4d.your-secret"
```

> [!WARNING]
>
> Treat API keys like passwords. Call the API from a server, never from browser JavaScript or a mobile app where users could read the key.

## Create, rotate, and revoke keys

Team admins manage keys under **Settings → Integrations → API** in the dashboard. See [Connect the API](https://www.carstoragesoftware.com/docs/settings/connect-api.md) for the walkthrough.

* **Name keys after their purpose**, such as *Website inventory feed*, so you know what breaks if you revoke one.
* **Set an expiration** for keys handed to contractors. Expired keys return `401 API key expired`.
* **Revoke** a key the moment it might have leaked. Revoked keys return `401 API key revoked` immediately.
* **Rotate** by creating a new key, updating the integration, then revoking the old key.

## Scopes

Each key carries a list of scopes. A request fails with `403 Missing scope: <scope>` when the key lacks the scope that endpoint needs. Each endpoint page lists its scope at the top of the description.

Write access is **never** implied by read access. A key that needs to create cars needs both `read:cars` (to look them up) and `write:cars`.

| Scope | Grants |
| - | - |
| `read:cars` / `write:cars` | Cars, car events, and car photos (read also lists event types) |
| `read:customers` / `write:customers` | Customers |
| `read:contacts` / `write:contacts` | Contacts |
| `read:locations` / `write:locations` | Locations |
| `read:parking` / `write:parking` | Parking zones, spots, and assignments |
| `read:appointments` / `write:appointments` | Appointments (read also lists event types) |
| `read:communications` / `write:communications` | Communication threads and messages |
| `read:campaigns` / `write:campaigns` | Marketing campaigns (audiences, content steps, sends), social posts, connected social accounts, and the marketing calendar |
| `read:templates` / `write:templates` | Marketing templates |
| `read:forms` / `write:forms` | Marketing forms and submissions |
| `read:social-events` / `write:social-events` | Social events, RSVP options, invites, and RSVPs (read also covers the marketing calendar) |
| `read:marketing-assets` / `write:marketing-assets` | Marketing assets and asset folders |
| `read:billing` / `write:billing` | Products and prices, subscriptions, invoices, and customer balances. Write sends or voids invoices and creates plan change requests (a staff member approves each one in the dashboard). No scope charges cards, refunds, or moves money. |

> [!NOTE]
>
> Some writes touch more than one resource. For example, logging a drop-off into a parking spot with `POST /cars/{id}/events` also needs `write:parking`.

## API turned off

If a team admin turns the API integration off, every key on that team returns `403 API is disabled for this team` until it is turned back on. The keys themselves are kept.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.