Suomi.fi Authentication

generated: '2026-11-11'
method: derived
source: openapi/_original/suomi-fi-ptv-v12-openapi.json
docs: https://kehittajille.suomi.fi/palvelut/palvelutietovaranto/rajapinta-ja-arkkitehtuuriuudistus/api-avaimen-kayttoohje-ptv-rajapintaversio-12
summary:
  types:
  - apiKey
  api_key_in:
  - header
  required: true
  note: >-
    PTV API v12 requires an API key (x-api-key header) on every read. The v12 contract applies
    apiKeyHeader to 30 of its 32 GET operations; the two it leaves unsecured (/health/liveness,
    /health/readiness) also answered 403 "Invalid or missing api key" from the production gateway
    without a key. The contract also declares an http bearer (JWT) scheme, but no operation uses it,
    so it is not an access requirement. The provider's own pages agree: from API version 12 an API key
    is needed for both the search (OUT) and import (IN) APIs, issued by self-service.
schemes:
- name: apiKeyHeader
  type: apiKey
  in: header
  parameter: x-api-key
  description: API-key auth
  applies_to: 30 of 32 operations (every /api/v12 read; not the two /health probes)
  sources:
  - openapi/_original/suomi-fi-ptv-v12-openapi.json
- name: bearerAuth
  type: http
  scheme: bearer
  bearerFormat: JWT
  description: Bearer auth
  applies_to: none - declared in components.securitySchemes, referenced by no operation and no root security
  sources:
  - openapi/_original/suomi-fi-ptv-v12-openapi.json
version_note: >-
  "The OUT interface needs no login" is true of PTV API version 11, not version 12. The v11 contract
  (https://api.palvelutietovaranto.suomi.fi/swagger/v11/swagger.json, title "PTV Open Api version 11")
  leaves 46 of its 55 GETs unsecured and secures writes with OAuth2 implicit via palveluhallinta.suomi.fi;
  an anonymous GET of /api/v11/CodeList/GetLanguageCodes returned 200 JSON. The production Swagger UI at
  https://api.palvelutietovaranto.suomi.fi/swagger/ui/index.html loads that v11 document, not a petstore
  sample and not v12. The provider states v11 is supported until April 2027 (date to be specified).
x-evidence:
  fetched: '2026-11-11'
  probes:
  - {url: 'https://docs.palvelutietovaranto.suomi.fi/api-documentation/v12/openapi.json', status: 200, content_type: application/json, note: 'identical to openapi/_original/suomi-fi-ptv-v12-openapi.json'}
  - {url: 'https://api-gw.palvelutietovaranto.suomi.fi/api/v12/languages', status: 403, note: 'no key: "Invalid or missing api key"'}
  - {url: 'https://api-gw.palvelutietovaranto.suomi.fi/health/liveness', status: 403, note: 'no key: "Invalid or missing api key", although the contract declares no security here'}
  - {url: 'https://api.palvelutietovaranto.suomi.fi/swagger/ui/index.js', status: 200, note: 'configObject.urls = /swagger/v11/swagger.json ("Version 11")'}
  - {url: 'https://api.palvelutietovaranto.suomi.fi/api/v11/CodeList/GetLanguageCodes', status: 200, note: 'anonymous v11 read'}
  - {url: 'https://kehittajille.suomi.fi/services/servicecatalogue/utilisation-of-fsc-data-and-integrations/technical-documentation-for-the-implementer-of-the-integration-api-version-12', status: 200, note: '"Starting in API version 12, you will need an API key for using both the search and import APIs."'}