Transport for Finland Authentication: API Key Access (2026)

Authentication overview

Transport for Finland, through its Digitransit platform, provides APIs for public transport data, including journey planning and real-time vehicle information. Authentication mechanisms for these APIs are designed to differentiate between commercial and non-commercial usage, ensuring appropriate access control and resource allocation. For most commercial applications, an API key is the standard method for authentication. Non-commercial projects, such as academic research or personal applications, may benefit from more open access, as detailed in the Digitransit developer documentation.

The primary purpose of authentication within the Transport for Finland API ecosystem is to manage access to data, enforce rate limits, and enable monitoring of API usage. This approach helps maintain the stability and availability of the service for all users. Developers integrating with the Digitransit HSL GraphQL API or accessing GTFS data will need to understand these authentication requirements to ensure their applications function correctly and compliantly.

Supported authentication methods

Transport for Finland's Digitransit platform primarily supports API key authentication for controlled access to its services. The choice of authentication method depends largely on the intended use case and the specific API being consumed. The table below outlines the main authentication approach:

API keys serve as a simple yet effective method for client identification and authorization. They are typically generated through a developer portal and should be treated as sensitive credentials. While not as robust as token-based authentication (e.g., OAuth 2.0), API keys are suitable for server-to-server communication or applications where the API key can be securely stored and managed.

Getting your credentials

To obtain the necessary credentials for authenticating with Transport for Finland's Digitransit APIs, follow these steps:

1. Visit the Developer Portal: Navigate to the Digitransit developer section. This portal is the central hub for all developer resources, including API documentation and access management.
2. Register for an Account: If you do not already have one, create a developer account. This typically involves providing an email address and setting a password. Account registration is a prerequisite for requesting API keys.
3. Request an API Key: Within your developer account dashboard, locate the section for API key management. You will likely need to provide details about your application, such as its name, purpose, and expected usage volume. This information helps Transport for Finland understand your needs and allocate appropriate access.
4. Review Terms of Use: Before generating your key, carefully read and accept the terms of use for the APIs. These terms detail usage policies, rate limits, and any commercial restrictions.
5. Generate and Store Your Key: Once approved, your API key will be generated. Copy this key immediately and store it securely. Treat your API key like a password; it grants access to the API on your behalf.

For non-commercial use cases, it is advisable to consult the Digitransit documentation directly, as some endpoints may offer open access without requiring a key, or may have a simplified registration process.

Authenticated request example

When using an API key for authentication with Transport for Finland's Digitransit GraphQL API, the key is typically included as a custom HTTP header. The specific header name might vary, but a common practice is to use Authorization or a custom header like x-api-key. Always refer to the official GraphQL API reference for the exact header name required.

Here's an example of an authenticated request using JavaScript's fetch API, assuming the API key is passed via an x-api-key header:

const API_KEY = 'YOUR_API_KEY_HERE'; // Replace with your actual API key
const GRAPHQL_ENDPOINT = 'https://api.digitransit.fi/routing/v1/routers/hsl/index/graphql';

const query = `
  {
    stops(name: "Rautatientori") {
      name
      lat
      lon
    }
  }
`;

fetch(GRAPHQL_ENDPOINT, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': API_KEY, // Or 'Authorization': `Bearer ${API_KEY}` if specified
  },
  body: JSON.stringify({ query })
})
.then(response => {
  if (!response.ok) {
    throw new Error(`HTTP error! Status: ${response.status}`);
  }
  return response.json();
})
.then(data => {
  console.log('Stops data:', data);
})
.catch(error => {
  console.error('Error fetching data:', error);
});

In this example:

• API_KEY should be replaced with the actual API key you obtained from the Digitransit developer portal.
• The x-api-key header is included in the request to identify your application.
• The request body contains a GraphQL query to fetch data about stops named "Rautatientori".

Always verify the required header name and format in the Digitransit GraphQL API documentation, as authentication methods and header requirements can be updated.

Security best practices

Securing your API keys and managing authentication effectively are critical for protecting your application and ensuring continuous access to Transport for Finland's APIs. Adhering to these best practices helps mitigate common security risks:

1. Never Embed API Keys Directly in Client-Side Code: Exposing API keys in public client-side code (e.g., JavaScript in a browser) makes them easily discoverable and exploitable. Instead, use a backend server to proxy requests to the API, adding the API key on the server side.
2. Store API Keys Securely: API keys should be stored in environment variables, secure configuration files, or a secrets management service (e.g., AWS Secrets Manager, Google Secret Manager, Azure Key Vault). Avoid hardcoding them directly into your application's source code.
3. Use HTTPS for All API Communication: Ensure all calls to Transport for Finland's APIs are made over HTTPS. This encrypts the communication channel, protecting your API key and data from interception during transit.
4. Implement Rate Limiting and Monitoring: Even with an API key, implement client-side rate limiting and monitor your API usage for unusual patterns. This can help detect and respond to unauthorized use or abuse of your key.
5. Rotate API Keys Periodically: Regularly generate new API keys and revoke old ones. This practice minimizes the window of opportunity for a compromised key to be exploited.
6. Restrict API Key Permissions: If the Digitransit platform offers granular permissions for API keys, configure your keys with the minimum necessary permissions required for your application's functionality. This principle of least privilege reduces the impact of a compromised key.
7. Validate and Sanitize Inputs: Always validate and sanitize any user inputs that are used in API requests to prevent injection attacks or other vulnerabilities that could indirectly expose your credentials or compromise your application.
8. Review Access Logs: Regularly check the access logs provided by Transport for Finland (if available) to monitor who is accessing your APIs and to identify any suspicious activity.

By following these guidelines, developers can significantly enhance the security posture of their applications integrating with Transport for Finland's Digitransit APIs, protecting both their own systems and the integrity of the public transport data.