Authentication overview

Authentication for the Metro Lisboa API is a prerequisite for accessing its public transit data, which includes real-time schedules and journey planning information. The API utilizes industry-standard authentication mechanisms to secure data access and maintain system integrity. Developers are required to authenticate their requests to consume data, whether for server-to-server integration or for applications requiring user-specific data access.

The chosen authentication method depends on the nature of the application and the type of data being accessed. For direct application-level access to public, non-sensitive data, an API key is typically sufficient. However, for scenarios involving user data or requiring delegated authorization from a Metro Lisboa user, OAuth 2.0 is the recommended protocol. Both methods ensure that only authorized entities can interact with the API endpoints. All API communication is secured using HTTPS/TLS 1.2 or higher to encrypt data in transit, protecting against eavesdropping and tampering, a standard practice outlined by organizations like the W3C Security FAQ on HTTPS.

Supported authentication methods

The Metro Lisboa API supports two primary authentication methods:

  1. API Key Authentication: A simple, token-based authentication mechanism where a unique key is provided with each API request. This method is suitable for server-to-server interactions and accessing public data endpoints that do not require user-specific authorization.
  2. OAuth 2.0: An authorization framework that allows third-party applications to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access solely on its own behalf. Metro Lisboa uses OAuth 2.0 for scenarios requiring delegated authorization from individuals, such as accessing personalized journey preferences or notifications linked to a user account. More details on the OAuth 2.0 specification are available on OAuth.net's overview of OAuth 2.0.

The following table summarizes the key characteristics of each method:

Method When to Use Security Level Typical Credential
API Key Server-to-server communication, public data access, low-privilege operations Medium (depends on key secrecy) Alphanumeric string (e.g., apikey_YOURKEYHERE)
OAuth 2.0 User-specific data access, delegated authorization, access to sensitive endpoints High (token-based, refreshable, scope-controlled) Access Token, Refresh Token, Client ID, Client Secret

Getting your credentials

To obtain authentication credentials for the Metro Lisboa API, developers must register an application through the official Metro Lisboa Developer Portal, accessible via the Metro Lisboa homepage. The process typically involves the following steps:

  1. Developer Account Registration: Create a developer account on the Metro Lisboa Developer Portal. This usually requires providing basic contact information and agreeing to the API terms of service.

  2. Application Registration: Once logged in, register your application. During this step, you will provide details about your application, such as its name, description, and intended use. This information helps Metro Lisboa understand how their API is being consumed.

  3. Credential Generation:

    • For API Keys: Upon successful application registration, the Developer Portal will generate a unique API key for your application. This key should be treated as a secret and stored securely.
    • For OAuth 2.0: When registering an application that requires OAuth 2.0, you will be issued a Client ID and a Client Secret. You will also need to specify one or more Redirect URIs (callback URLs) where the authorization server will send the user back after they authorize your application. The Client Secret is highly sensitive and must be kept confidential, similar to a password for your application. The OAuth 2.0 framework relies on secure handling of these credentials, as detailed by RFC 6749, The OAuth 2.0 Authorization Framework.

  4. Scope Selection (OAuth 2.0 only): If using OAuth 2.0, you will typically need to define the scopes your application requires. Scopes limit the access your application has to a user's data or specific API functionalities. For example, a scope might be read:schedule or write:preferences. Requesting only the necessary scopes adheres to the principle of least privilege.

Always refer to the specific documentation within the Metro Lisboa Developer Portal for the most up-to-date and precise instructions on credential generation and management.

Authenticated request example

Here are examples of how to make authenticated requests using both API Key and OAuth 2.0. These examples assume you have already obtained your credentials.

API Key Example (HTTP Header)

For API Key authentication, the key is typically sent in a custom HTTP header or as a query parameter. Metro Lisboa's API prefers the X-API-Key header for enhanced security and cleaner URLs.

GET /v1/station_info?station_id=CPO HTTP/1.1
Host: api.metrolisboa.pt
X-API-Key: YOUR_METROLISBOA_API_KEY

curl -X GET "https://api.metrolisboa.pt/v1/station_info?station_id=CPO" \
     -H "Accept: application/json" \
     -H "X-API-Key: YOUR_METROLISBOA_API_KEY"

OAuth 2.0 Example (Bearer Token)

For OAuth 2.0, after your application has successfully completed the authorization flow and obtained an access token, it will be included in the Authorization header with the Bearer scheme.

Step 1: Obtain an Access Token (Conceptual)

This involves redirecting the user to Metro Lisboa's authorization server, where they grant permission, and your application receives an authorization code. Your application then exchanges this code for an access token and optionally a refresh token. The exact flow (e.g., Authorization Code Grant) depends on your application type.

Step 2: Make an API Request with the Access Token

GET /v1/user/journey_preferences HTTP/1.1
Host: api.metrolisboa.pt
Authorization: Bearer YOUR_OAUTH2_ACCESS_TOKEN

curl -X GET "https://api.metrolisboa.pt/v1/user/journey_preferences" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer YOUR_OAUTH2_ACCESS_TOKEN"

Replace YOUR_METROLISBOA_API_KEY and YOUR_OAUTH2_ACCESS_TOKEN with your actual, securely obtained credentials.

Security best practices

Adhering to security best practices is essential when integrating with any API, including Metro Lisboa's, to protect your application, user data, and the API itself. Failure to follow these guidelines can lead to unauthorized access, data breaches, and service interruptions.

  • Keep Credentials Confidential:

    • Never hardcode API keys or OAuth client secrets directly into your application's source code, especially for client-side applications.
    • Store API keys and client secrets in environment variables or a secure configuration management system.
    • For client-side applications (e.g., mobile apps, browser-based JavaScript), never expose your API key directly to the client. Instead, route requests through a secure backend that holds the key.

  • Use HTTPS/TLS for All Communications: Ensure all API requests are made over HTTPS. Metro Lisboa's API enforces this, but it's a fundamental principle for securing data in transit. This prevents man-in-the-middle attacks where sensitive information could be intercepted.

  • Implement Least Privilege:

    • For API keys, only grant the necessary permissions required for your application's functionality.
    • For OAuth 2.0, request only the scopes absolutely essential for your application. Do not ask for broader access than what your application truly needs. Users are also more likely to approve requests with minimal, clear scopes.

  • Secure OAuth 2.0 Implementations:

    • Protect Redirect URIs: Ensure your registered Redirect URIs are specific and secure. Validate the state parameter to prevent Cross-Site Request Forgery (CSRF) attacks.
    • Refresh Token Security: If using refresh tokens, store them securely and handle their expiry and renewal carefully. Never expose refresh tokens to client-side code.
    • PKCE for Public Clients: For public client applications (e.g., mobile apps, SPAs) using the Authorization Code flow, always implement Proof Key for Code Exchange (PKCE) to mitigate authorization code interception attacks.

  • Regularly Rotate Credentials: Periodically rotate your API keys and OAuth client secrets, especially if there is any suspicion of compromise. The Metro Lisboa Developer Portal provides mechanisms for key rotation.

  • Monitor API Usage: Keep an eye on your application's API usage patterns. Unusual spikes or requests from unexpected locations could indicate a compromised key or unauthorized access.

  • Error Handling and Logging: Implement robust error handling for authentication failures. Log authentication attempts and failures for auditing and debugging purposes, but ensure sensitive information like API keys or access tokens are not logged in plain text.