KEPLIN Docs

API:t ja GraphQL API-avaimet

API-avaimet

API-avainten luominen, rajaaminen ja mitätöiminen — ulkoisten järjestelmien pääsy sovellustesi GraphQL:ään.

Ulkoiset järjestelmät — asiakkaita synkronoiva ERP, tilauksia luova sivusto, laskutusintegraatio — kutsuvat sovellusten GraphQL:ää API-avaimella: salaisuudella, joka lähetetään jokaisen pyynnön otsakkeessa x-api-key. Avaimia hallitaan alustan tasolla ja ne ovat sovellusten kesken jaettuja: jokaisella avaimella on scope — valitset sovellukset ja, sovellusta kohden, kaikki endpointit tai vain osan. Laskutusintegraatio voi esimerkiksi lukea asiakkuuksia Asiakashallinta-sovelluksesta ja kirjoittaa dokumentteja toiseen sovellukseen yhdellä ainoalla avaimella.

Nota

Avaimet kuuluvat alustan ylläpitäjille: sivu API-avaimet on käytettävissä vain ylläpitäjätileille.

Sivu API-avaimet

Avaa valikko API-avaimet yleisessä navigoinnissa. Lista näyttää kaikki alustan avaimet:

Sarake Mikä se on
Nimi Avaimelle antamasi nimi — tunnistaa integraation.
Etuliite Avaimen ensimmäiset merkit (esim. amk_A1b2C3…) — niiden avulla tunnistat, mikä on mikä, näyttämättä koskaan koko avainta.
Scope Sovellukset, joihin se antaa pääsyn, ja sovellusta kohden ”kaikki endpointit” tai myönnettyjen lista.
Tila aktiivinen tai mitätöity.
Viimeksi käytetty Milloin avainta käytettiin viimeksi — ei koskaan, jos ei vielä ole.

Sivu API-avaimet, kunkin avaimen scope ja viimeisin käyttö.
Sivu API-avaimet, kunkin avaimen scope ja viimeisin käyttö.

Dica

Sarake Viimeksi käytetty on siivoustyökalusi: avain, jota ei ole käytetty kuukausiin, on mitätöintiehdokas.

API-avaimen luominen

  1. Paina Uusi API-avain.
  2. Anna Avaimen nimi — esim. integração-faturação.
  3. Merkitse kohdassa Scope — sallitut sovellukset ja endpointit mukaan otettavat sovellukset. Oletuksena jokainen merkitty sovellus myöntää ”Kaikki tämän sovelluksen endpointit.”
  4. Kiristääksesi pääsyä sovelluksessa merkitse Rajaa tiettyihin endpointeihin ja valitse API:t yksi kerrallaan. Taulu-API:ssa myöntö kattaa kaikki aktiiviset operaatiot — lista näyttää ”antaa pääsyn: getContas, addContas, …”, jotta tiedät tarkalleen, mitä myönnät.
  5. Paina Luo API-avain.

API-avaimen luontimodaali, scope sovelluksittain ja endpointeittain.
API-avaimen luontimodaali, scope sovelluksittain ja endpointeittain.

Avaimen kopiointi ja tallettaminen

Luomisen jälkeen ikkuna näyttää Avaimen selkotekstinä — yhden ainoan kerran. Kopioi se painikkeella Kopioi ja talleta se turvalliseen paikkaan (salaisuuksien hallintaan, tiimisi holviin). Kun suljet ikkunan, et enää näe sitä — alusta ei säilytä avainta selkona; jos hukkaat sen, voit vain mitätöidä sen ja luoda toisen.

Luotu avain, selkotekstinä ainoan kerran, Kopioi-painikkeineen.
Luotu avain, selkotekstinä ainoan kerran, Kopioi-painikkeineen.

Atenção

Kohtele avainta kuin salasanaa: älä laita sitä lähdekoodiin, URL:iin äläkä käyttäjien näytöille. Jos epäilet vuotoa, mitätöi heti — uuden avaimen luominen vie sekunteja.

Avaimen käyttäminen

Avain kulkee otsakkeessa x-api-key jokaisessa pyynnössä sovelluksen GraphQL-endpointiin:

curl -X POST 'https://o-teu-host/api/graphql/gestao-clientes' \
  -H 'content-type: application/json' \
  -H 'x-api-key: amk_………' \
  -d '{"query":"query { getContas(take: 5) { id nome } }"}'

Kunkin API:n välilehti Docs generoi tämän esimerkin (ja JavaScript-muunnelman) valmiiksi oikealla operaatiolla — vain avaimesi puuttuu.

Mitä avain näkee ja ei näe:

  • Vain julkaistut API:t — luonnoksia ei koskaan, edes koko sovelluksen scopella.
  • Vain sen, minkä scope myöntää: scopen ulkopuolisen sovelluksen kutsuminen palauttaa 403 — API key not authorised for this project; scopen ulkopuolisen endpointin kutsuminen 403 — API key not authorised for this endpoint.
  • Aina sovelluksen pääversion (tai käytetyn osoitteen julkaistun version) — ei koskaan developerin työversiota.

Rajat ja virheet

Jokaisella avaimella on pyyntökatto minuuttia kohden. Virhevastaukset, jotka integraation tulee osata käsitellä:

Vastaus Merkitys Mitä tehdä
401 Avain puuttuu, on kelvoton, vanhentunut tai mitätöity. Tarkista otsake ja avaimen tila listalta.
403 Avain kelvollinen mutta ilman pääsyä sovellukseen tai endpointiin. Säädä scope — luo uusi avain oikealla scopella.
429 Pyyntökatto minuuttia kohden saavutettu. Odota otsakkeen retry-after kertoma aika ja yritä uudelleen.

Avaimen mitätöiminen

  1. Paina listalla rivin mitätöintikuvaketta.
  2. Vahvista painikkeella Mitätöi avain.

Mitätöinti on välitön: kaikki tätä avainta käyttävät sovellukset menettävät pääsyn seuraavassa pyynnössä. Mitätöityä avainta ei voi ottaa uudelleen käyttöön — se jää listalle merkittynä mitätöity, merkinnäksi.

Miksi ei…?

  • Hukkasin avaimen — voinko nähdä sen uudelleen? Et. Avain selkotekstinä näytetään vain luontihetkellä. Mitätöi vanha ja luo toinen.
  • Minun pitää antaa pääsy vielä yhteen endpointiin — muokkaanko avainta? Scope määritetään luonnissa. Luo uusi avain täydellä scopella, vaihda se integraatioon ja mitätöi vanha.
  • Miksi integraatio saa 403 uudesta endpointista? Avain rajattiin tiettyihin endpointeihin eikä uusi ole listalla — sama lääke: uusi avain oikealla scopella.
  • Antaako avain pääsyn sovelluksen näyttöihin? Ei. Avain puhuu vain GraphQL-endpointin kanssa. Sovelluksen käyttäjätilit ovat eri asia, ja niitä hallitaan itse sovelluksen asetuksissa.