# Scopes

Source: https://www.geardex.app/api-docs/scopes

API access requires the GearDex Studio plan and a scoped Studio API key.

Scopes keep every GearDex integration narrow, understandable, and easy to revoke without affecting the rest of your workflow.

## Scope model

A key can include multiple scopes. Every endpoint declares the scope it requires, and GearDex checks that permission before accessing account data. Read access never implies write access.

Least privilege

Start with read-only scopes. Add a write scope only after the integration has a specific, reviewed operation that needs it.

## Available scopes

Nine scopes cover the six v1 resources. The routes column lists what each scope allows.

**GearDex Studio API scopes**

| Scope | Access | Grants | Routes |
| --- | --- | --- | --- |
| gear:read | read | Read inventory, kits, lost and stolen reports, shutter counts, and consumables. | `GET /gearGET /gear/{id}GET /gear/{id}/shutter-readingsGET /categoriesGET /locationsGET /kitsGET /kits/{id}GET /incidentsGET /consumables` |
| gear:write | write | Create, update, and delete inventory and kits; report incidents; log counts; adjust stock. | `POST /gearPATCH /gear/{id}DELETE /gear/{id}POST /gear/{id}/shutter-readingsPOST /kitsPATCH /kits/{id}DELETE /kits/{id}POST /incidentsPATCH /incidents/{id}POST /consumables/{id}/adjust` |
| shoots:read | read | Read shoot plans, packing lists, and rentals. | `GET /shootsGET /shoots/{id}/gearGET /rentalsGET /jobsGET /jobs/{id}GET /clientsGET /clients/{id}GET /shoots/{id}/deliverablesGET /shoots/{id}/profit` |
| shoots:write | write | Create, update, and delete shoot plans, packing lists, and rentals. | `POST /shootsPATCH /shoots/{id}DELETE /shoots/{id}POST /shoots/{id}/gearPATCH /shoots/{id}/gearPOST /rentalsPATCH /rentals/{id}DELETE /rentals/{id}POST /clientsPATCH /clients/{id}POST /clients/{id}/activitiesPOST /shoots/{id}/deliverablesPOST /shoots/{id}/deliverables/deliver` |
| maintenance:read | read | Read service records, schedules, providers, and cost. | `GET /maintenance` |
| maintenance:write | write | Create, update, and delete service records for owned gear. | `POST /maintenancePATCH /maintenance/{id}DELETE /maintenance/{id}` |
| documents:read | read | Read document metadata, warranty timelines, and insurance coverage. | `GET /documentsGET /insuranceGET /insurance/{id}` |
| analytics:read | read | Read portfolio-level inventory and operations summaries. | `GET /analytics` |
| profile:read | read | Read account and Studio profile metadata. | `GET /profile` |
| loans:read | read | Read loans with their items, gear flags, and availability for dates. | `GET /loansGET /loans/{id}GET /flagsGET /availability` |
| loans:write | write | Check gear out and in, extend or cancel loans, and flag gear. | `POST /loansPATCH /loans/{id}POST /loans/{id}/check-inPOST /flagsPATCH /flags/{id}` |
| bookings:read | read | Read bookings and inquiries from the Site. | `GET /bookingsGET /inquiries` |
| bookings:write | write | Approve or decline booking requests. | `PATCH /bookings/{id}` |
| money:read | read | Read quotes, invoices, installments, and payments. | `GET /quotesGET /invoices` |
| money:write | write | Create and send quotes, and record invoice payments. | `POST /quotesPOST /quotes/{id}/sendPOST /invoices/{id}/payments` |

## Recommended scope sets

**Recommended GearDex scope combinations**

| Integration | Scopes | Use it to |
| --- | --- | --- |
| `Inventory reporter` | `gear:read + analytics:read` | Summarize inventory composition and portfolio totals without making changes. |
| `Production briefing` | `shoots:read + gear:read + maintenance:read` | Assess upcoming work, available equipment, and service conflicts. |
| `Warranty monitor` | `documents:read + gear:read` | Associate coverage timelines with the affected equipment. |
| `Service queue sync` | `maintenance:read + maintenance:write + gear:read` | Create and update repair records while validating owned gear references. |
| `Lending desk` | `loans:read + loans:write + gear:read` | Check gear out and in from a kiosk, Slack bot, or rental tool, and chase overdue returns. |
| `Shoot planning automation` | `shoots:read + shoots:write + gear:read` | Draft and maintain production plans using live inventory context. |

## Missing scope errors

A valid key that lacks the endpoint's required permission receives a `403` response. Create or update a purpose-specific key instead of broadening unrelated integrations.

**403 response**

```json
{
  "error": "Missing required scope: maintenance:write",
  "code": "insufficient_scope"
}
```

See [Responses and errors](https://www.geardex.app/api-docs/errors) for every authentication code.