Julkinen rajapinta

Helpdesk tarjoaa yhden julkisen rajapinnan: GraphQL-päätepisteen. Jokainen skeeman operaatio on tavoitettavissa selaimen ulkopuolelta henkilökohtaisella käyttöoikeustunnisteella (Personal Access Token, PAT).

Tämä sivu on sopimus — mikä on vakaata, miten tunnistaudut, mihin käyttöoikeusalueet oikeuttavat ja minkä muotoisia virheet ovat. hdmx-komentorivityökalu on rakennettu sen päälle, ja rajapinnan versiointi kertoo, miten tämä pinta kehittyy.

Päätepiste

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

• <subdomain> yksilöi tilisi (sama tunnus, jolla kirjaudut sisään).
• <version> on päivätty rajapinnan versio, esimerkiksi 2026-07 — katso rajapinnan versiointi. Voit myös jättää versio-osan pois ja kutsua osoitetta …/backend/<subdomain>/graphql; tällöin pyynnön käsittelee vanhin tuettu versio, ja jokainen vastaus kertoo, mikä versio siihen vastasi.

Tunnistautuminen

Lähetä henkilökohtainen käyttöoikeustunniste Bearer-tunnisteena:

Authorization: Bearer hdmx_<random>

PAT on pitkäikäinen (mutta sillä on pakollinen voimassaolon päättymispäivä), sillä on käyttöoikeusalueet, se on rajattu IP-osoitteisiin ja se voidaan mitätöidä. Tunniste on sidottu yhteen tiliin: sen esittäminen toisen tilin aliverkkotunnukselle hylätään koodilla HTTP 401.

Tunnisteen luominen

Luo ja hallitse tunnisteita itse agenttisovelluksessa kohdassa Settings → API tokens:

1. Napsauta New token.
2. Anna sille nimi, jonka tunnistat myöhemmin.
3. Valitse voimassaoloaika (enintään 365 päivää — vaihtoehtoa "ei koskaan" ei ole).
4. Määritä käyttöoikeuskäytäntö — kytke päälle täsmälleen ne resurssit, joita tämä tunniste tarvitsee, lukuoikeudella tai luku- ja kirjoitusoikeudella. Oletuksena mihinkään ei ole pääsyä.
5. Lisää sallittujen listalle vähintään yksi IP-osoite tai CIDR (pakollista — katso Sallittujen IP-osoitteiden lista). Lomake voi lisätä nykyisen IP-osoitteesi puolestasi.
6. Tarkista ja luo. Koko tunniste näytetään täsmälleen kerran — kopioi se heti. Tallennettuna on vain tiiviste, joten sitä ei voi näyttää uudelleen; jos hukkaat sen, kierrätä tunniste saadaksesi uuden.

Myöhemmin voit muokata tunnisteen käyttöoikeuskäytäntöä ja sallittujen listaa, kierrättää sen (myöntää uuden salaisuuden, kun vanha toimii vielä lyhyen siirtymäajan, jotta vaihto onnistuu ilman katkoa) sekä mitätöidä sen. Jokaisesta tunnisteesta näkyy, milloin ja mistä sitä on viimeksi käytetty, sekä loki viimeaikaisesta toiminnasta.

Käyttöoikeusalueet

Pääsy on karkeajakoista ja jäsennelty resurssiperheiden mukaan. Tunnisteella on kiinteä joukko käyttöoikeusalueita; jokainen ylimmän tason operaatio tarkistaa yhden niistä.

Käyttöoikeusalue	Antaa oikeuden
tickets:read	Lukea tikettejä, viestejä, luonnoksia, historiaa, liitteitä ja raportteja
tickets:write	Luoda / päivittää / poistaa tikettejä, julkaista viestejä ja ladata liitteitä. Sisältää tickets:read
chat:read	Lukea chatteja, keskusteluja, viestejä ja istuntoja
chat:write	Lähettää agentin viestejä sekä liittyä / poistua / sulkea / avata keskusteluja uudelleen. Sisältää chat:read
customers:read	Lukea asiakastietueita
customers:write	Luoda / päivittää / yhdistää asiakastietueita. Sisältää customers:read
settings:read	Lukea tilin asetuksia (osastot, tilat, prioriteetit, postilaatikot — ilman salaisuuksia)

Postilaatikoiden tunnistetietokenttiä (IMAP/SMTP-käyttäjätunnuksia, -salasanoja ja -palvelimia) ei koskaan palauteta tunnisteelle käyttöoikeusalueesta riippumatta — nämä salaisuudet kuuluvat sähköpostipalveluntarjoajallesi ja pysyvät julkisen rajapinnan ulottumattomissa.

Virheiden luokittelu

GraphQL-vastaukset käyttävät kenttää errors[].extensions.code:

Koodi	Merkitys	HTTP
SCOPE_DENIED	Tunnisteelta puuttuu vaadittu käyttöoikeusalue. extensions.valid_values luettelee alueet, jotka riittäisivät operaatioon	200
RATE_LIMITED	Tunnisteen pyyntökiintiö on käytetty loppuun. extensions.retryAfter on sekuntien määrä nollaukseen, ja Retry-After-otsake sisältää saman luvun	429
INVALID_API_TOKEN	Tunnistetta ei löydy, se on virheellisen muotoinen tai muutoin käyttökelvoton	200

Mitätöidyt tunnisteet, vanhentuneet tunnisteet, tilien väliset ristiriidat ja sallittujen IP-osoitteiden listan hylkäykset torjutaan ennen kyselyn suoritusta ja näkyvät muodossa HTTP 401 ilman GraphQL-runkoa. Tulkitse tunnisteella tehdyn pyynnön 401 näin: "tämä tunniste ei enää kelpaa tähän pyyntöön — tarkista sen voimassaolo, käyttöoikeusalueet ja sallittujen IP-osoitteiden lista."

Pyyntörajat

Jokainen tunnisteella tehty pyyntö palauttaa otsakkeet:

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

Oletuskiintiö on 120 pyyntöä minuutissa tunnistetta kohti. Jokainen pyyntö maksaa 1 riippumatta siitä, lukeeko vai kirjoittaako se. Ylitys palauttaa koodin HTTP 429, otsakkeen Retry-After ja arvon extensions.code = "RATE_LIMITED"; hyvin käyttäytyvä asiakas odottaa nollaushetkeen asti.

Sallittujen IP-osoitteiden lista

Jokaisella itse luodulla tunnisteella täytyy olla vähintään yksi IP-osoite tai CIDR — "mistä tahansa IP-osoitteesta" toimivia tunnisteita ei ole. Jokaisen pyynnön lähde-IP verrataan tunnisteen listaan; osuman puuttuminen hylätään koodilla HTTP 401 ja arvolla extensions.sub_code = "ip_not_allowed".

• IPv4, IPv6 ja CIDR-alueet hyväksytään kaikki. Yhtä konetta varten käytä /32 (IPv4) tai /128 (IPv6).
• Alueet tarkistetaan ja normalisoidaan tallennettaessa.
• Sallittujen listaa voi muokata luonnin jälkeen — muokkaaminen ei muuta salaisuutta.

Käytä tunnistetta vakaasta lähtöpisteestä: CI-ajurista, ajastetusta työstä, kiinteästä toimiston NAT-osoitteesta tai omilta palvelimiltasi tunnetulta IP-alueelta. Vuotanut tunniste on hyödytön mistä tahansa sallittujen listansa ulkopuolelta.

Tunnisteen toiminta

Jokainen tunnisteen tekemä tunnistautunut pyyntö kirjataan: ajankohta, operaation nimi, lähde-IP, lopputulos (onnistuminen, virhe, pyyntörajan ylitys, käyttöoikeusalueen epäys, mitätöity tai vanhentunut) sekä vasteaika. Tämä on jälki, joka kannattaa tarkistaa, jos tunniste käyttäytyy odottamattomasti.

Versiointi ja poistuvat osat

Rajapinta versioidaan päivätyillä YYYY-MM-versioilla. Kiinnitä versio URL-osoitteeseen, niin se pysyy vakaana vähintään 12 kuukautta; poistuvista osista ilmoitetaan vastausten yhteydessä ennen kuin mitään käyttämääsi katoaa. Koko käytäntö on kuvattu kohdassa Rajapinnan versiointi.

Skeeman tutkiminen

Skeema kuvaa itsensä: käytä tavallista GraphQL-introspektiota versioitua päätepistettä vasten tyyppien luomiseen ja rajapinnan tutkimiseen. Vuorovaikutteinen GraphQL Playground löytyy osoitteesta …/backend/<subdomain>/playground.

curl-pikaopas

Esimerkeissä oletetaan palvelin helpdesk.example.com, aliverkkotunnus acme, versio 2026-07 ja tunniste muuttujassa $TOKEN.

Nykyisen käyttäjän lukeminen (mikä tahansa käyttöoikeusalue)

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 } }"}'

Viimeisimpien tikettien listaus (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 }
  }'

Julkisen vastauksen julkaiseminen (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"
      }
    }
  }'

Päivittäisessä käytössä hdmx-komentorivityökalu kääräisee koko tämän pinnan sujuviksi komennoiksi.