# API-referens

Referensen nedan renderas direkt ur `/openapi.json` — den är genererad, inte handskriven, och kan därför inte glida ifrån API:t.

## Bas-URL:er

| Miljö | Bas-URL | Används till |
| --- | --- | --- |
| STAGE | `https://staging.zesec.com/api` | Utveckling och test. Alla får access hit. |
| PROD | `https://api.zesec.com/api` | Skarp drift mot riktiga enheter. Kräver verifierat partnerskap. |

Sökvägarna är identiska i båda miljöerna. Serverväljaren i referensen nedan byter mellan dem.

## De fyra centrala endpointerna

| Metod & sökväg | Auth | Body / parameter | Ger |
| --- | --- | --- | --- |
| `POST /api/auth/login-by-phone` | — | `{ "phoneNumber": "{{phoneNumber}}", "password": "{{password}}" }` | `AccessToken` + `RefreshToken` |
| `GET /api/user/device` | `Bearer <AccessToken>` | — | Enhetslista för mappning och cache |
| `PUT /api/device/{deviceId}/unlock` | `Bearer <AccessToken>` | `{deviceId}` i sökvägen (heltal) | Utför upplåsningen |
| `POST /api/auth/refresh` | — | `{ "refreshToken": "<RefreshToken>" }` | Nytt, roterat tokenpar |

Utöver dessa publicerar referensen `POST /api/auth/login`, `POST /api/auth/login-by-email`, `POST /api/auth/logout`, `GET /api/user/location`, `GET /api/device/{deviceId}` och `PUT /api/device/{deviceId}/unlock/{lockId}`. Allt annat i den interna specen filtreras bort innan dokumentet serveras.

> **lockId behövs bara för enheter med flera lås** — `PUT /api/device/{deviceId}/unlock/{lockId}` riktar upplåsningen mot ett specifikt lås på en enhet som har fler än ett. Har er enhet ett lås använder ni endpointen utan `{lockId}`.

> **Interaktiv referens** — Referensen renderas i webbläsaren. Läser du det här som text: hämta dokumentet direkt från /openapi.json (eller /openapi.yaml).

## Maskinläsbara varianter

- [/openapi.json — det serverade dokumentet (live när källan svarar)](/openapi.json)
- [/openapi.yaml — samma dokument som YAML](/openapi.yaml)
- [/openapi.pinned.json — den fastlåsta kopian, ändras aldrig oväntat](/openapi.pinned.json)
- [/llms.txt — index för AI-agenter](/llms.txt)

Svaret från `/openapi.json` bär headern `X-Spec-Source: live` eller `pinned` så att ni kan se vilket dokument ni fick, plus en `ETag` för villkorlig hämtning.

## Fel och statuskoder

Varje skyddad operation dokumenterar sina 4xx-svar. Hela katalogen med vad klienten ska göra i varje läge finns på [Statuskoder & felsvar](/docs/errors).