Time Door Authentication: API Security & Credential Management

Authentication overview

Time Door provides machine learning services for predictive analytics, demand forecasting, and anomaly detection. Access to the Time Door API is secured through API keys, which are used to authenticate client applications making requests. This mechanism ensures that all interactions with Time Door's services are authorized and that data remains protected. The authentication process is designed to be straightforward, allowing developers to integrate Time Door's capabilities into their applications efficiently while maintaining security standards.

When an authenticated request is made to the Time Door API, the provided API key is validated against the system's records. Successful validation grants access to the requested resources and operations, such as submitting data for forecasting or retrieving model results. Failed validation results in an authentication error, preventing unauthorized access. Time Door emphasizes the importance of managing API keys securely to prevent misuse and maintain the integrity of user data and models.

Supported authentication methods

Time Door primarily supports API key authentication, implemented as a Bearer Token in the HTTP Authorization header. This method is common for RESTful APIs due to its simplicity and effectiveness for server-to-server communication and client applications where the key can be securely stored and transmitted over HTTPS.

While API keys are the primary method, it's essential to understand their characteristics and when to use them. API keys are generally suitable for identifying the calling application or user and enforcing rate limits, but they differ from more complex protocols like OAuth 2.0 for delegated authorization or OpenID Connect for identity verification.

API Key (Bearer Token)

This is the standard authentication method for the Time Door API. An API key is a unique string that identifies your application or user account. It must be included in every API request.

• Mechanism: The API key is sent in the Authorization header of HTTP requests with the Bearer scheme.
• Purpose: Authenticates the client application and grants access based on the permissions associated with the key.
• Security: Relies on the confidentiality of the API key. All communications should occur over HTTPS to encrypt the key in transit.

Authentication Methods Comparison

Getting your credentials

To interact with the Time Door API, you need to obtain an API key. This key is generated and managed through the Time Door Console, your central hub for managing projects, models, and API access.

Steps to obtain an API key:

1. Sign Up/Log In: Navigate to the Time Door Console and either sign up for a new account (starting with the Developer Plan, which offers 500 API calls/month and 1 project) or log in to an existing one.
2. Access Project Settings: Once logged in, navigate to the specific project you intend to use with the API. If you haven't created a project, you will need to do so first.
3. Generate API Key: Within your project settings, locate the "API Keys" or "Credentials" section. You will typically find an option to generate a new API key. Time Door's documentation provides specific instructions on this process, including any options for key naming or permission scoping.
4. Copy and Secure: After generation, the API key will be displayed. It is crucial to copy this key immediately and store it securely. For security reasons, Time Door often displays the key only once upon creation and does not allow retrieval later. If lost, you would typically revoke the old key and generate a new one.

Refer to the Time Door API reference for the most current and detailed instructions on credential generation and management within the console.

Authenticated request example

Once you have obtained your API key, you can include it in your API requests. The Time Door API expects the key to be passed as a Bearer Token in the Authorization HTTP header. Here's an example using curl and a Python SDK snippet.

cURL Example

This curl command demonstrates how to make a GET request to a hypothetical Time Door endpoint, including your API key:

curl -X GET \
  'https://api.timedoor.io/v1/projects/your_project_id/forecasts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json'

Replace YOUR_API_KEY with your actual API key and your_project_id with your Time Door project identifier. The specific endpoint paths and request bodies will vary depending on the API operation you are performing, such as submitting data or requesting a forecast.

Python SDK Example

Time Door provides a Python SDK that simplifies API interactions, including authentication. The SDK handles the proper inclusion of the API key in request headers.

import os
from timedoor import TimeDoorClient
from timedoor.models import ForecastRequest

# It is recommended to load your API key from environment variables
api_key = os.environ.get("TIMEDOOR_API_KEY")
if not api_key:
    raise ValueError("TIMEDOOR_API_KEY environment variable not set.")

# Initialize the client with your API key
client = TimeDoorClient(api_key=api_key)

try:
    # Example: Create a forecast request
    forecast_data = ForecastRequest(
        project_id="your_project_id",
        series_data=[{"timestamp": "2023-01-01T00:00:00Z", "value": 100}],
        horizon=7,
        # ... other forecast parameters
    )
    
    forecast_response = client.forecast.create(forecast_data)
    print("Forecast created successfully:", forecast_response.id)
    
    # Example: Retrieve a forecast
    retrieved_forecast = client.forecast.get(forecast_response.id)
    print("Retrieved forecast data:", retrieved_forecast.results)

except Exception as e:
    print(f"An error occurred: {e}")

In this Python example, the TimeDoorClient is initialized with the API key, which is then automatically used for subsequent API calls. Storing API keys in environment variables (TIMEDOOR_API_KEY) is a recommended practice for security, preventing the key from being hardcoded directly in your source code.

Security best practices

Securing your API keys and ensuring the integrity of your Time Door integrations is paramount. Adhering to these best practices helps mitigate risks associated with unauthorized access and data breaches.

1. Keep API Keys Confidential: Treat your API keys like passwords. Never hardcode them directly into client-side code (e.g., JavaScript in a browser) or commit them to public version control systems like GitHub. Store them in secure environment variables, secret management services, or encrypted configuration files on your server.
2. Use Environment Variables: For server-side applications, storing API keys as environment variables (as demonstrated in the Python SDK example) is a standard and effective method. This keeps keys out of your codebase and allows for easy rotation without code changes.
3. Restrict Key Permissions: If Time Door offers granular permissions for API keys (e.g., read-only, specific project access), generate keys with the minimum necessary permissions required for the task. This limits the blast radius if a key is compromised. Consult the Time Door security documentation for details on permission scoping.
4. Rotate API Keys Regularly: Periodically rotate your API keys. This practice limits the window of exposure for a compromised key. The Time Door Console typically provides functionality to revoke old keys and generate new ones.
5. Monitor API Usage: Regularly review your API usage logs and metrics in the Time Door Console. Unusual spikes in activity or requests from unexpected locations could indicate a compromised key.
6. Enforce HTTPS/TLS: All communication with the Time Door API occurs over HTTPS (Hypertext Transfer Protocol Secure). This encrypts data in transit, protecting your API key and sensitive data from interception. Always ensure your application is configured to use HTTPS when making API calls. This is a fundamental principle for securing web communications.
7. Implement IP Whitelisting (if available): If Time Door supports IP whitelisting, configure your API keys to only accept requests originating from a predefined set of trusted IP addresses. This adds an extra layer of security, preventing unauthorized access even if a key is stolen.
8. Error Handling: Implement robust error handling in your applications to gracefully manage authentication failures. Avoid exposing sensitive information in error messages.

By following these guidelines, developers can build secure and reliable integrations with the Time Door API, protecting their data and maintaining the integrity of their forecasting and analytics workflows.