API-avaimen käyttöohje (PTV rajapintaversio 12)
API-avain rajapintaversiossa 12
- API-avain otetaan käyttöön PTV:n rajapintaversiosta 12 eteenpäin sekä tietojen haku (OUT) - että tuontirajapinnassa (IN).
- API-avain on ympäristökohtainen ja se tulee tilata jokaiselle toteutettavalle integraatiolle erikseen.
Digi- ja väestötietovirasto tarvitsee tiedot toteuttamastanne integraatiosta sekä yhteyshenkilöistä, jotta voimme viestiä teille integraatioon vaikuttavista asioista. API-avaimen saaminen edellyttää tietojen antamista.
API-avaimen tilaaminen, hallinta ja käyttäminen
Valitse käyttäjätunnus API-avaimen tilaamiseen
API-avain luodaan ja sitä hallitaan PTV:n API-avaimen hallinnointikäyttöliittymässä.
- API-avaimen on hyvä olla käyttäjäorganisaatiokohtainen, eikä it-toimittajakohtainen. Käyttäjäorganisaatio siis itse luo ja hallinnoi API-avainta ja toimittaa sen it-toimittajalle. Jos käyttäjäorganisaatiolla on useampi integraatio, jokaiselle tulee tilata oma API-avain.
- Kun luot uutta tunnusta, anna käyttäjätunnukseksi sähköpostiosoite, jota haluat jatkossa käyttää palveluun tunnistautumisessa ja API-avaimen hallinnassa.
- Huomaa, että vain tällä sähköpostiosoitteella voi jatkossa hallita API-avainta.
- Käyttäjätunnukseksi on suositeltavaa antaa jokin organisaation yhteiskäyttöinen sähköpostiosoite, joka ei ole vain yhden ihmisen käytössä.
Kirjaudu palveluun
- Siirry palveluun: tuotantoympäristön API-avaimen hallinnointikäyttöliittymäAvautuu uuteen ikkunaan. tai asiakastestiympäristön API-avaimen hallinnointikäyttöliittymäAvautuu uuteen ikkunaan.
- Syötä valitsemasi sähköpostiosoite
- Lähetämme sähköpostiin vahvistuskoodin
- Syötä saamasi vahvistuskoodi API-avaimen hallinnointikäyttöliittymään
Lisää käyttäjäorganisaation tiedot
- Organisaation tiedot
- Organisaation yhteyshenkilön tiedot
Luo ja toimita integraatiokohtainen API-avain
Voit luoda useita API-avaimia eri integraatioita varten (enintään 10 kpl).
- Valitse uuden API-avaimen luominen
- Täydennä tiedot integraatiosta ja sen toteuttavasta IT-toimittajasta (jos eri kuin käyttäjäorganisaatio).
- Luo API avain
- Kopioi API-avain (ks. kuva alla) ja toimita se salatulla sähköpostilla tai muulla tietoturvallisella tavalla IT-toimittajallesi.
API-avain on voimassa luontihetkestä yhden vuoden ja sen voimassaoloa voi jatkaa vuoden kerrallaan.
API-avainten hallinta
- Voit luoda uuden API-avaimen.
- Voit pidentää valitsemasi API-avaimen voimassaoloaikaa (maksimissaan vuosi eteenpäin voimassaolon jatkohetkestä).
- Voit poistaa käytöstä valitsemasi API-avaimen.
Huomaa, että
- API-avaimet ovat integraatiokohtaisia ja niitä voi olla maksimissaan 10 kappaletta.
Mitä tehdä, jos API-avaimen luonut sähköpostiosoite ei enää ole käytössä?
- Luo organisaation käyttöön uusi API-avain uudella sähköpostiosoitteella.
- Ota yhteyttä osoitteeseen ptv-tuki@dvv.fi, joka sulkee vanhan API-avaimen. API-avain kyllä sulkeutuu viimeistään vuoden päästä, mutta on turvallisempaa pyytää API-avaimen sulkemista jo aikaisemmin ja ottaa uusi API-avain käyttöön.
Asiakastestiympäristön linkki | Kuvaus |
|---|---|
Asiakastestiympäristön API-avaimen hallinnointikäyttöliittymäAvautuu uuteen ikkunaan. | Tilaa ja hallitse API-avainta |
Asiakastestiympäristön rajapintadokumentaatioAvautuu uuteen ikkunaan. | Rajapintaversion 12 dokumentaatio (Scalar) |
Rajapinnan tekninen osoite (API-avaimella): https://api-gw.palvelutietovaranto.trn.suomi.fi | Käytä ohjelmallisiin rajapintakutsuihin API-avaimen kanssa (esim. curl). |
Tuotantoympäristön (betaversio) linkki | Kuvaus |
|---|---|
Tuotantoympäristön API-avaimen hallinnointikäyttöliittymäAvautuu uuteen ikkunaan. | Tilaa ja hallitse API-avainta |
Tuotantoympäristön rajapintadokumentaatioAvautuu uuteen ikkunaan. | Rajapintaversion 12 dokumentaatio (Scalar) |
Rajapinnan tekninen osoite: https://api-gw.palvelutietovaranto.suomi.fi | Käytä ohjelmallisiin rajapintakutsuihin API-avaimen kanssa (esim. curl). Huom. Rajapintaversion 12 hakurajapinta on tuotannossa betaversiona. |
Lisää API-avain rajapintakutsun HTTP-headereihin avaimella x-api-key.
Esimerkki API-avaimen käytöstä asiakastestiympäristössä (curl)
curl 'https://api-gw.palvelutietovaranto.trn.suomi.fi/api/v12/municipality-codes?page=1&pageSize=10' -H 'x-api-key: laita-api-avain-tähän'Esimerkki API-avaimen käytöstä API-dokumentaation (scalar) kutsuissa
API-avain kannattaa ottaa käyttöön päätasolla, jolloin se tulee automaattisesti mukaan yksittäisiin rajapintakutsuihin (ks. alla oleva kuva):
- Siirry API-dokumentaation (scalar) yläosaan
- Valitse kohdasta Authentication: apiKeyHeader
- Kopioi API-avaimesi arvo kohtaan: Value
-d720f40441ef65ca8cbd8f00fbd2994c.WEBP)