Authentication overview

BC Ferries provides digital interfaces for accessing real-time schedules, booking services, and operational updates. Secure interaction with these services requires authentication, a process that verifies the identity of a user or application attempting to access protected resources. The primary goal of BC Ferries' authentication framework is to ensure that data exchanges are authorized and secure, protecting both user information and system integrity. This is achieved through industry-standard protocols designed for API security.

The authentication mechanisms employed by BC Ferries are designed to accommodate various integration scenarios, from simple data retrieval to complex transactional operations like booking and payment processing. Developers integrating with BC Ferries' APIs must understand these methods to ensure their applications comply with security requirements and maintain reliable access. Adherence to specified authentication flows is critical for successful and sustained API usage.

BC Ferries prioritizes the security of its digital infrastructure. As such, all API interactions are expected to occur over encrypted channels, typically using Transport Layer Security (TLS) version 1.2 or higher. This encryption safeguards data in transit, preventing unauthorized interception and tampering, a fundamental aspect of modern web security practices as detailed by the World Wide Web Consortium's security FAQ.

Supported authentication methods

BC Ferries supports multiple authentication methods, each suited for different use cases and offering varying levels of security and complexity. The choice of method depends on the nature of the application and the specific API endpoints being accessed. All methods require a form of credential management, which is detailed in the subsequent sections.

API Keys

API keys are a common and straightforward method for authenticating requests to public or semi-public APIs. An API key is a unique identifier that is passed with each request, typically in a header or as a query parameter. For BC Ferries, API keys grant access to read-only data, such as public schedules or vessel positions, where user-specific or sensitive information is not involved. They offer a simple way to track API usage and enforce rate limits.

OAuth 2.0

OAuth 2.0 is an authorization framework that enables third-party applications to obtain limited access to an HTTP service, either on behalf of a resource owner (e.g., a user) or by allowing the application to obtain access on its own behalf. For BC Ferries, OAuth 2.0 is used for operations requiring user-specific data or actions, such as making or modifying bookings, accessing user profiles, or processing payments. It involves a more complex flow, typically including an authorization server, resource server, and client application, as described by the OAuth 2.0 specification.

The OAuth 2.0 implementation for BC Ferries likely uses common grant types such as the Authorization Code flow for web applications and potentially the Client Credentials flow for server-to-server interactions where the application acts on its own behalf. This framework provides a robust mechanism for delegated authorization without sharing user credentials directly with the client application.

The following table summarizes the supported authentication methods:

Method When to Use Security Level
API Key Accessing public, read-only data (e.g., schedules, vessel status). Moderate (identifies application, not user; susceptible to key compromise if not secured).
OAuth 2.0 Accessing user-specific data or performing transactional operations (e.g., bookings, payments). High (delegated authorization, token-based, user consent required).

Getting your credentials

To integrate with BC Ferries' APIs and authenticate your requests, you must first obtain the necessary credentials. This process typically involves registering your application on the BC Ferries developer portal or a designated partner portal.

Developer Portal Registration

  1. Access the Developer Portal: Navigate to the BC Ferries developer documentation section, likely accessible via the BC Ferries travel information page or a dedicated developer sub-domain.
  2. Create an Account: If you don't already have one, create a developer account. This typically requires an email address, password, and agreement to terms of service.
  3. Register Your Application: Within the developer portal, you will find an option to register a new application. During registration, you will need to provide details such as:
    • Application Name: A descriptive name for your application.
    • Application URL: The primary URL of your application.
    • Redirect URIs (for OAuth 2.0): For OAuth 2.0 applications, you must specify one or more redirect URIs. These are the URLs to which the user will be redirected after granting or denying access to your application. These URIs must be exact matches to what is registered.
    • Application Type: (e.g., web application, mobile application, server-side service).
  4. Obtain Credentials: Upon successful application registration, the portal will issue your credentials:
    • API Key: For API key-based authentication, a unique string will be provided.
    • Client ID and Client Secret: For OAuth 2.0, you will receive a Client ID (a public identifier for your application) and a Client Secret (a confidential key used to authenticate your application with the authorization server). The Client Secret must be kept confidential and never exposed in client-side code.
  5. Store Credentials Securely: It is crucial to store your API keys and Client Secrets securely. Refer to the Security Best Practices section for guidance.

Authenticated request example

The following examples demonstrate how to make authenticated requests using both API keys and OAuth 2.0. These examples assume you have already obtained your credentials.

API Key Example (GET /schedules)

For API key authentication, the key is typically passed in a custom HTTP header, such as X-API-Key, or as a query parameter. Using a header is generally preferred for security reasons.

curl -X GET \
  'https://api.bcferries.com/v1/schedules?routeId=TSA-SWB' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Accept: application/json'

In this example, YOUR_API_KEY should be replaced with the actual API key obtained from the developer portal. The Accept: application/json header indicates that the client prefers a JSON response.

OAuth 2.0 Example (GET /bookings/{bookingId})

For OAuth 2.0, you first need to obtain an access token. This involves an authorization flow where the user grants your application permission. Once you have an access token, it is included in the Authorization header using the Bearer scheme.

Step 1: Obtain an Access Token (example using Authorization Code Flow)

This is a simplified representation. The actual process involves redirecting the user to BC Ferries' authorization server, where they log in and grant consent, followed by your application exchanging an authorization code for an access token at the token endpoint.

# Exchange Authorization Code for Access Token
curl -X POST \
  'https://auth.bcferries.com/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code&code=YOUR_AUTHORIZATION_CODE&redirect_uri=YOUR_REDIRECT_URI&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET'

The response will contain an access_token, token_type (usually 'Bearer'), expires_in, and potentially a refresh_token.

Step 2: Make an Authenticated Request with the Access Token

curl -X GET \
  'https://api.bcferries.com/v1/bookings/12345' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/json'

Here, YOUR_ACCESS_TOKEN is the token received from the OAuth 2.0 token endpoint. This token provides your application with temporary, scoped access to the user's booking information.

Security best practices

Implementing strong security practices is paramount when integrating with any API, especially those handling personal or transactional data. Adhering to these guidelines will help protect your application and its users.

  1. Keep Credentials Confidential:
    • API Keys: Never embed API keys directly in client-side code (e.g., JavaScript in a web browser or mobile application). Instead, use a backend server to make API calls, storing the keys securely on the server. If client-side usage is unavoidable for specific public data, restrict the key's permissions.
    • Client Secrets: Client Secrets for OAuth 2.0 are highly sensitive. They must be stored securely on your server and never exposed in client-side code, mobile applications, or public repositories.
    • Environment Variables: Store API keys and client secrets as environment variables or in secure configuration management systems rather than hardcoding them into your application code.
  2. Use HTTPS/TLS: Always ensure all communications with BC Ferries APIs occur over HTTPS. This encrypts data in transit, protecting credentials and sensitive information from interception. BC Ferries APIs enforce TLS 1.2+ for all connections, as is standard practice for secure web communication.
  3. Implement OAuth 2.0 Securely:
    • Redirect URIs: Register specific and strict redirect URIs in the developer portal. Use fully qualified URLs, not wildcard domains, to prevent authorization code interception.
    • State Parameter: Always use the state parameter in OAuth 2.0 authorization requests to prevent Cross-Site Request Forgery (CSRF) attacks. The state parameter should be a unique, unguessable value generated by your application for each request.
    • Token Expiration: Respect access token expiration times. Implement mechanisms to refresh tokens before they expire using refresh tokens, if provided, to maintain continuous access without re-authenticating the user.
    • Scope Management: Request only the necessary scopes (permissions) that your application requires. Over-requesting permissions increases the attack surface.
  4. Error Handling and Logging: Implement robust error handling for authentication failures. Avoid returning verbose error messages that could reveal sensitive information. Log authentication attempts and failures for monitoring and auditing purposes, but ensure logs do not contain raw credentials.
  5. Rate Limiting: Be aware of and respect any rate limits imposed by BC Ferries APIs. Excessive requests can lead to temporary or permanent blocking of your API key or client. Implement exponential backoff for retries to handle rate limit errors gracefully.
  6. Regular Audits: Periodically review your application's security configurations, credential storage, and API usage patterns to identify and mitigate potential vulnerabilities. Keep your dependencies and libraries updated to address known security flaws.