Offentlig API

Helpdesken tilbyr ett offentlig API: et GraphQL-endepunkt. Alle operasjoner i skjemaet kan nås utenfor nettleseren med et personlig tilgangstoken (Personal Access Token, PAT).

Denne siden er kontrakten — hva som er stabilt, hvordan du autentiserer deg, hva scopes gir tilgang til, og hvordan feil er utformet. hdmx-CLI-et er bygget oppå den, og API-versjonering beskriver hvordan flaten utvikler seg.

Endepunktet

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

<subdomain> identifiserer kontoen din (samme navn som du logger inn med).
<version> er en datert API-versjon som 2026-07 — se API-versjonering. Du kan også utelate versjonsleddet og kalle …/backend/<subdomain>/graphql; da betjenes forespørselen av den eldste støttede versjonen, og hvert svar forteller deg hvilken versjon som svarte.

Autentisering

Send et personlig tilgangstoken som Bearer-legitimasjon:

Authorization: Bearer hdmx_<random>

Et PAT er langlivet (med obligatorisk utløpsdato), har scopes, er IP-begrenset og kan tilbakekalles. Det er bundet til én konto: å legge fram et token mot en annen kontos subdomene avvises med HTTP 401.

Opprette et token

Opprett og administrer tokener selv i agentappen under Settings → API tokens:

Klikk New token.
Gi det et navn du kjenner igjen senere.
Velg en utløpsdato (opptil 365 dager — det finnes ikke «aldri»).
Angi en tilgangspolicy — slå på nøyaktig de ressursene dette tokenet trenger, med lese- eller lese- og skrivetilgang. Som standard er ingenting tilgjengelig.
Legg minst én IP-adresse eller CIDR til tillatelseslisten (påkrevd — se IP-tillatelsesliste). Skjemaet kan legge inn din nåværende IP for deg.
Se over og opprett. Hele tokenet vises nøyaktig én gang — kopier det med en gang. Bare en hash lagres, så det kan aldri vises igjen; mister du det, roterer du tokenet for å få et nytt.

Senere kan du redigere tokenets tilgangspolicy og tillatelsesliste, rotere det (utstede en ny hemmelighet mens den gamle fortsatt virker i en kort overgangsperiode, så du kan bytte uten nedetid) og tilbakekalle det. Hvert token viser når og hvorfra det sist ble brukt, pluss en logg over nylig aktivitet.

Scopes

Tilgangen er grovmasket og delt inn etter ressursfamilier. Et token bærer et fast sett med scopes; hver operasjon på øverste nivå sjekker ett av dem.

Scope	Gir tilgang til
`tickets:read`	Å lese saker, meldinger, utkast, historikk, vedlegg og rapporter
`tickets:write`	Å opprette / oppdatere / slette saker, poste meldinger og laste opp vedlegg. Innebærer `tickets:read`
`chat:read`	Å lese chatter, samtaler, meldinger og økter
`chat:write`	Å sende agentmeldinger og bli med i / forlate / lukke / gjenåpne samtaler. Innebærer `chat:read`
`customers:read`	Å lese kundeoppføringer
`customers:write`	Å opprette / oppdatere / slå sammen kundeoppføringer. Innebærer `customers:read`
`settings:read`	Å lese kontoinnstillinger (avdelinger, statuser, prioriteter, postbokser — uten hemmeligheter)

Legitimasjonsfeltene for postbokser (IMAP/SMTP-brukernavn, -passord og -verter) returneres aldri til et token, uansett scope — disse hemmelighetene tilhører e-postleverandøren din og holdes utenfor rekkevidde for det offentlige API-et.

Feiltaksonomi

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

Kode	Betydning	HTTP
`SCOPE_DENIED`	Tokenet mangler nødvendig scope. `extensions.valid_values` lister opp scopene som ville oppfylt operasjonen	200
`RATE_LIMITED`	Forespørselsbudsjettet per token er brukt opp. `extensions.retryAfter` er antall sekunder til nullstilling, og `Retry-After`-hodet inneholder samme tall	429
`INVALID_API_TOKEN`	Tokenet finnes ikke, er feilformet eller er ubrukelig av andre grunner	200

Tilbakekalte tokener, utløpte tokener, uoverensstemmelser mellom kontoer og avvisninger fra IP-tillatelseslisten avvises før spørringen kjøres, og kommer tilbake som HTTP 401 uten GraphQL-kropp. Behandle en 401 på en tokenforespørsel som «dette tokenet er ikke lenger gyldig for denne forespørselen — sjekk utløpsdato, scopes og IP-tillatelsesliste.»

Ratebegrensninger

Hver tokenforespørsel har disse hodene:

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

Standardbudsjettet er 120 forespørsler i minuttet per token. Hver forespørsel koster 1, enten den leser eller skriver. Overskridelse gir HTTP 429 med et Retry-After-hode og extensions.code = "RATE_LIMITED"; en veloppdragen klient venter til nullstillingstidspunktet.

IP-tillatelsesliste

Hvert selvbetjente token må ha minst én IP eller CIDR — det finnes ingen «hvilken som helst IP»-tokener. Kilde-IP-en til hver forespørsel måles mot tokenets liste; et bom avvises med HTTP 401 og extensions.sub_code = "ip_not_allowed".

IPv4, IPv6 og CIDR-områder godtas alle. Bruk /32 (IPv4) eller /128 (IPv6) for én enkelt vert.
Områder valideres og normaliseres når du lagrer dem.
Tillatelseslisten kan redigeres etter opprettelsen — redigering endrer ikke hemmeligheten.

Bruk et token fra et stabilt utgangspunkt: en CI-runner, en planlagt jobb, en fast kontor-NAT eller dine egne servere i et kjent IP-område. Et lekket token er ubrukelig fra alle steder utenfor tillatelseslisten sin.

Tokenaktivitet

Hver autentiserte forespørsel et token gjør, registreres: tidspunktet, operasjonsnavnet, kilde-IP-en, utfallet (vellykket, feil, ratebegrenset, scope avvist, tilbakekalt eller utløpt) og svartiden. Dette er sporet du skal sjekke hvis et token oppfører seg uventet.

Versjonering og utfasing

API-et versjoneres med daterte YYYY-MM-versjoner. Lås én i URL-en, så holder den seg stabil i minst 12 måneder; utfasinger varsles underveis før noe du bruker forsvinner. Se API-versjonering for hele retningslinjen.

Utforske skjemaet

Skjemaet beskriver seg selv: bruk vanlig GraphQL-introspeksjon mot det versjonerte endepunktet for å generere typer og utforske flaten. Den interaktive GraphQL Playground finnes på …/backend/<subdomain>/playground.

curl-hurtigstart

Eksemplene forutsetter verten helpdesk.example.com, subdomenet acme, versjonen 2026-07 og et token i $TOKEN.

Les gjeldende bruker (hvilket som helst 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 } }"}'

List opp nylige saker (`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 offentlig 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 bruk pakker hdmx-CLI-et hele denne flaten inn i lettvinte kommandoer.

Offentlig API

Endepunktet​

Autentisering​

Opprette et token​

Scopes​

Feiltaksonomi​

Ratebegrensninger​

IP-tillatelsesliste​

Tokenaktivitet​

Versjonering og utfasing​

Utforske skjemaet​

curl-hurtigstart​

Les gjeldende bruker (hvilket som helst scope)​

List opp nylige saker (tickets:read)​

Post et offentlig svar (tickets:write)​