Offentligt API

Helpdesken udstiller ét offentligt API: et GraphQL-endpoint. Alle operationer i skemaet kan nås uden for browseren med et personligt adgangstoken (Personal Access Token, PAT).

Denne side er kontrakten — hvad der er stabilt, hvordan du godkendes, hvad scopes giver adgang til, og hvordan fejl er opbygget. hdmx-CLI'en er bygget oven på den, og API-versionering beskriver, hvordan fladen udvikler sig.

Endpointet

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

<subdomain> identificerer din konto (det samme navn, du logger ind med).
<version> er en dateret API-version såsom 2026-07 — se API-versionering. Du kan også udelade versionsleddet og kalde …/backend/<subdomain>/graphql; så betjenes anmodningen af den ældste understøttede version, og hvert svar fortæller dig, hvilken version der svarede.

Godkendelse

Send et personligt adgangstoken som Bearer-legitimation:

Authorization: Bearer hdmx_<random>

Et PAT er langtidsholdbart (med en obligatorisk udløbsdato), har scopes, er IP-begrænset og kan tilbagekaldes. Det er bundet til én konto: at præsentere et token på en anden kontos subdomæne afvises med HTTP 401.

Oprettelse af et token

Opret og administrer selv tokens i agentappen under Settings → API tokens:

Klik på New token.
Giv det et navn, du kan genkende senere.
Vælg en udløbsdato (op til 365 dage — der findes ikke "aldrig").
Angiv en adgangspolitik — slå netop de ressourcer til, som dette token har brug for, med læse- eller læse-/skriveadgang. Som udgangspunkt er der ingen adgang.
Tilføj mindst én IP-adresse eller CIDR til allowlisten (påkrævet — se IP-allowliste). Formularen kan tilføje din nuværende IP for dig.
Gennemgå og opret. Det fulde token vises præcis én gang — kopiér det med det samme. Kun et hash gemmes, så det kan aldrig vises igen; mister du det, så rotér tokenet for at få et nyt.

Senere kan du redigere et tokens adgangspolitik og allowliste, rotere det (udstede en ny hemmelighed, mens den gamle stadig virker i en kort overgangsperiode, så du kan skifte uden nedetid) og tilbagekalde det. Hvert token viser, hvornår og hvorfra det sidst blev brugt, plus en log over den seneste aktivitet.

Scopes

Adgangen er grovkornet og opdelt efter ressourcefamilier. Et token bærer et fast sæt scopes; hver operation på øverste niveau kontrollerer ét af dem.

Scope	Giver adgang til
`tickets:read`	At læse sager, beskeder, kladder, historik, vedhæftninger og rapporter
`tickets:write`	At oprette / opdatere / slette sager, poste beskeder og uploade vedhæftninger. Indebærer `tickets:read`
`chat:read`	At læse chats, samtaler, beskeder og sessioner
`chat:write`	At sende agentbeskeder samt tilslutte sig / forlade / lukke / genåbne samtaler. Indebærer `chat:read`
`customers:read`	At læse kundeposter
`customers:write`	At oprette / opdatere / flette kundeposter. Indebærer `customers:read`
`settings:read`	At læse kontoindstillinger (afdelinger, statusser, prioriteter, postkasser — uden hemmeligheder)

Postkassernes legitimationsfelter (IMAP/SMTP-brugernavne, -adgangskoder og -værter) returneres aldrig til et token, uanset scope — de hemmeligheder tilhører din e-mailudbyder og forbliver uden for det offentlige APIs rækkevidde.

Fejltaksonomi

GraphQL-svar bruger errors[].extensions.code:

Kode	Betydning	HTTP
`SCOPE_DENIED`	Tokenet mangler det nødvendige scope. `extensions.valid_values` viser de scopes, der ville opfylde operationen	200
`RATE_LIMITED`	Anmodningsbudgettet pr. token er opbrugt. `extensions.retryAfter` er antal sekunder til nulstilling, og `Retry-After`-headeren indeholder samme tal	429
`INVALID_API_TOKEN`	Tokenet blev ikke fundet, er misdannet eller på anden måde ubrugeligt	200

Tilbagekaldte tokens, udløbne tokens, uoverensstemmelser mellem konti og afvisninger fra IP-allowlisten afvises, før forespørgslen kører, og optræder som HTTP 401 uden GraphQL-krop. Betragt en 401 på en tokenanmodning som "dette token er ikke længere gyldigt til denne anmodning — tjek dets udløbsdato, scopes og IP-allowliste."

Hastighedsgrænser

Hver tokenanmodning har disse headere:

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

Standardbudgettet er 120 anmodninger i minuttet pr. token. Hver anmodning koster 1, uanset om den læser eller skriver. Overskridelse giver HTTP 429 med en Retry-After-header og extensions.code = "RATE_LIMITED"; en velopdragen klient venter til nulstillingstidspunktet.

IP-allowliste

Hvert selvbetjent token skal indeholde mindst én IP eller CIDR — der findes ingen "enhver IP"-tokens. Kilde-IP'en for hver anmodning holdes op mod tokenets liste; en manglende match afvises med HTTP 401 og extensions.sub_code = "ip_not_allowed".

IPv4, IPv6 og CIDR-intervaller accepteres alle. Brug /32 (IPv4) eller /128 (IPv6) til en enkelt vært.
Intervaller valideres og normaliseres, når du gemmer dem.
Allowlisten kan redigeres efter oprettelsen — redigering ændrer ikke hemmeligheden.

Brug et token fra et stabilt udgangspunkt: en CI-runner, et planlagt job, en fast kontor-NAT eller dine egne servere i et kendt IP-interval. Et lækket token er ubrugeligt alle steder uden for dets allowliste.

Tokenaktivitet

Hver godkendt anmodning, et token foretager, registreres: tidspunktet, operationens navn, kilde-IP'en, udfaldet (succes, fejl, hastighedsbegrænset, scope afvist, tilbagekaldt eller udløbet) og svartiden. Det er sporet, du skal tjekke, hvis et token opfører sig uventet.

Versionering og udfasning

API'et versioneres med daterede YYYY-MM-versioner. Fastlås en i URL'en, og den holder sig stabil i mindst 12 måneder; udfasninger varsles undervejs, før noget, du bruger, forsvinder. Se API-versionering for hele politikken.

Udforskning af skemaet

Skemaet beskriver sig selv: brug almindelig GraphQL-introspektion mod det versionerede endpoint for at generere typer og udforske fladen. Den interaktive GraphQL Playground findes på …/backend/<subdomain>/playground.

curl-hurtigstart

Eksemplerne antager værten helpdesk.example.com, subdomænet acme, versionen 2026-07 og et token i $TOKEN.

Læs den aktuelle bruger (ethvert 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 } }"}'

Vis de seneste sager (`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 }
  }'

Post et offentligt 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"
      }
    }
  }'

Til daglig brug pakker hdmx-CLI'en hele denne flade ind i lettilgængelige kommandoer.

Offentligt API

Endpointet​

Godkendelse​

Oprettelse af et token​

Scopes​

Fejltaksonomi​

Hastighedsgrænser​

IP-allowliste​

Tokenaktivitet​

Versionering og udfasning​

Udforskning af skemaet​

curl-hurtigstart​

Læs den aktuelle bruger (ethvert scope)​

Vis de seneste sager (tickets:read)​

Post et offentligt svar (tickets:write)​