API-avaimen käyttöohje (PTV rajapintaversio 12)

Beta - sisältö on kesken

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.
Asiakastestiympäristössä API-avain on toistaiseksi valinnainen, mutta muuttuu pakolliseksi kevään 2026 aikana.

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).
Rajapinnan tekninen osoite (ilman API-avainta): https://api.palvelutietovaranto.trn.suomi.fi	Käytä ohjelmallisiin rajapintakutsuihin ilman API-avainta (esim. curl). Huom. Käytettävissä toistaiseksi.

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.

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

Valitse Authentication -kohdasta apiKeyHeader ja kopioi API-avain kohtaan Value.

Päivitetty: 5.5.2026

Digitalisoi asiointipolkusi

Tehosta tiedonhallintaa

Paranna palveluiden laatua

Turvaa tietosi

Jaa, avaa ja hyödynnä tietoa