Publikt API

Helpdesken erbjuder ett enda publikt API: en GraphQL-endpunkt. Varje operation i schemat går att nå utanför webbläsaren med en personlig åtkomsttoken (Personal Access Token, PAT).

Den här sidan är kontraktet — vad som är stabilt, hur du autentiserar dig, vad scopes ger tillgång till och hur fel är utformade. hdmx-CLI:t är byggt ovanpå det, och API-versionshantering beskriver hur ytan utvecklas.

Endpunkten

POST https://<your-host>/backend/<subdomain>/api/<version>/graphql

<subdomain> identifierar ditt konto (samma namn som du loggar in med).
<version> är en daterad API-version som 2026-07 — se API-versionshantering. Du kan även utelämna versionsdelen och anropa …/backend/<subdomain>/graphql; då hanteras begäran av den äldsta version som stöds, och varje svar talar om vilken version som svarade.

Autentisering

Skicka en personlig åtkomsttoken som Bearer-uppgift:

Authorization: Bearer hdmx_<random>

En PAT är långlivad (men har ett obligatoriskt utgångsdatum), bär scopes, är IP-begränsad och kan återkallas. Den är bunden till ett konto: att visa upp en token mot ett annat kontos underdomän avvisas med HTTP 401.

Skapa en token

Skapa och hantera tokens själv i agentappen under Settings → API tokens:

Klicka på New token.
Ge den ett namn som du känner igen senare.
Välj ett utgångsdatum (upp till 365 dagar — det finns inget "aldrig").
Ange en åtkomstpolicy — slå på exakt de resurser som denna token behöver, med läs- eller läs- och skrivrättighet. Som standard ges ingen åtkomst alls.
Lägg till minst en IP-adress eller CIDR i tillåtelselistan (obligatoriskt — se IP-tillåtelselista). Formuläret kan lägga in din nuvarande IP åt dig.
Granska och skapa. Hela token visas exakt en gång — kopiera den direkt. Endast en hash lagras, så den kan aldrig visas igen; tappar du bort den roterar du token för att få en ny.

Senare kan du redigera en tokens åtkomstpolicy och tillåtelselista, rotera den (utfärda en ny hemlighet medan den gamla fortsätter fungera under en kort övergångsperiod, så att du kan byta utan driftstopp) och återkalla den. Varje token visar när och varifrån den senast användes, plus en logg över den senaste aktiviteten.

Scopes

Åtkomsten är grovkornig och indelad efter resursfamiljer. En token bär en fast uppsättning scopes; varje operation på toppnivå kontrollerar ett av dem.

Scope	Ger rätt att
`tickets:read`	Läsa ärenden, meddelanden, utkast, historik, bilagor och rapporter
`tickets:write`	Skapa / uppdatera / ta bort ärenden, publicera meddelanden och ladda upp bilagor. Innefattar `tickets:read`
`chat:read`	Läsa chattar, konversationer, meddelanden och sessioner
`chat:write`	Skicka agentmeddelanden samt gå med i / lämna / stänga / återöppna konversationer. Innefattar `chat:read`
`customers:read`	Läsa kundposter
`customers:write`	Skapa / uppdatera / slå samman kundposter. Innefattar `customers:read`
`settings:read`	Läsa kontoinställningar (avdelningar, statusar, prioriteter, brevlådor — utan hemligheter)

Brevlådornas inloggningsfält (IMAP/SMTP-användarnamn, -lösenord och -värdar) returneras aldrig till en token, oavsett scope — dessa hemligheter tillhör din e-postleverantör och hålls utom räckhåll för det publika API:et.

Feltaxonomi

GraphQL-svar använder errors[].extensions.code:

Kod	Betydelse	HTTP
`SCOPE_DENIED`	Token saknar det scope som krävs. `extensions.valid_values` listar de scopes som skulle uppfylla operationen	200
`RATE_LIMITED`	Begärandebudgeten per token är förbrukad. `extensions.retryAfter` är antal sekunder till återställning, och huvudet `Retry-After` innehåller samma tal	429
`INVALID_API_TOKEN`	Token hittades inte, är felformad eller går av annan anledning inte att använda	200

Återkallade tokens, utgångna tokens, felmatchningar mellan konton och avslag från IP-tillåtelselistan avvisas innan frågan körs och visas som HTTP 401 utan GraphQL-kropp. Behandla en 401 på en tokenbegäran som "den här token är inte längre giltig för den här begäran — kontrollera utgångsdatum, scopes och IP-tillåtelselista."

Hastighetsgränser

Varje tokenbegäran bär dessa huvuden:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 96
X-RateLimit-Reset: 1715692800

Standardbudgeten är 120 begäranden per minut och token. Varje begäran kostar 1, oavsett om den läser eller skriver. Att gå över ger HTTP 429 med ett Retry-After-huvud och extensions.code = "RATE_LIMITED"; en välartad klient väntar till återställningstidpunkten.

IP-tillåtelselista

Varje token som skapas i självbetjäning måste bära minst en IP eller CIDR — det finns inga "vilken IP som helst"-tokens. Käll-IP:n för varje begäran matchas mot tokenens lista; en miss avvisas med HTTP 401 och extensions.sub_code = "ip_not_allowed".

IPv4, IPv6 och CIDR-intervall accepteras alla. Använd /32 (IPv4) eller /128 (IPv6) för en enskild värd.
Intervall valideras och normaliseras när du sparar dem.
Tillåtelselistan går att redigera efter skapandet — en redigering ändrar inte hemligheten.

Använd en token från en stabil utgångspunkt: en CI-runner, ett schemalagt jobb, en fast kontors-NAT eller egna servrar i ett känt IP-intervall. En läckt token är oanvändbar från varje plats utanför sin tillåtelselista.

Tokenaktivitet

Varje autentiserad begäran som en token gör registreras: tidpunkten, operationens namn, käll-IP:n, utfallet (lyckat, fel, hastighetsbegränsat, nekat scope, återkallad eller utgången) och svarstiden. Det är detta spår du ska granska om en token beter sig oväntat.

Versionshantering och utfasning

API:et versionshanteras med daterade YYYY-MM-versioner. Lås fast en i URL:en, så håller den sig stabil i minst 12 månader; utfasningar aviseras i själva trafiken innan något du använder försvinner. Se API-versionshantering för hela policyn.

Utforska schemat

Schemat beskriver sig självt: använd vanlig GraphQL-introspektion mot den versionerade endpunkten för att generera typer och utforska ytan. Den interaktiva GraphQL Playground finns på …/backend/<subdomain>/playground.

curl-snabbstart

Exemplen utgår från värden helpdesk.example.com, underdomänen acme, versionen 2026-07 och en token i $TOKEN.

Läs aktuell användare (valfritt scope)

curl -sS https://helpdesk.example.com/backend/acme/api/2026-07/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ currentUser { id email firstname lastname } }"}'

Lista senaste ärenden (`tickets:read`)

curl -sS https://helpdesk.example.com/backend/acme/api/2026-07/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query ($first: Int!) {
      ticketList(first: $first) {
        edges { node { code subject status { name } updatedAt } }
      }
    }",
    "variables": { "first": 10 }
  }'

Publicera ett publikt svar (`tickets:write`)

curl -sS https://helpdesk.example.com/backend/acme/api/2026-07/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation ($input: SaveTicketInput!) {
      saveTicket(input: $input) {
        ticket { code }
        error { code message }
      }
    }",
    "variables": {
      "input": {
        "id": "TICKET-UUID-HERE",
        "message": "Thanks — fixing this now.",
        "messageType": "PUBLIC"
      }
    }
  }'

För det dagliga arbetet paketerar hdmx-CLI:t hela den här ytan bakom smidiga kommandon.

Publikt API

Endpunkten​

Autentisering​

Skapa en token​

Scopes​

Feltaxonomi​

Hastighetsgränser​

IP-tillåtelselista​

Tokenaktivitet​

Versionshantering och utfasning​

Utforska schemat​

curl-snabbstart​

Läs aktuell användare (valfritt scope)​

Lista senaste ärenden (tickets:read)​

Publicera ett publikt svar (tickets:write)​