Understanding API Keys & Security

When you create an API Ingest datasource in Twinnoverse, the system automatically generates a unique API Key. This key is a critical component for ensuring that only authorized systems can send data to your datasource. This guide explains what the API key is, how it works, and how to handle it securely.

What is an API Key? #

An API Key is a long, unique string of characters that acts like a password for your datasource. It is a form of “token-based authentication.” Any request sent to the Ingestion URL must present this key to prove that it has permission to add data.

In Twinnoverse, the API Key is used where the key is sent in the Authorization header of your HTTP request.

Example Header:

Authorization: your_unique_api_key_goes_here

If a request is sent to the Ingestion URL without a valid API Key, or with an incorrect one, the server will reject the request with an Unauthorized error, and no data will be saved.

Security Best Practices: Treat Your API Key Like a Password #

The security of your data stream depends on keeping your API Key secret. If your key is exposed, a malicious actor could send false data to your datasource, corrupting your digital twin’s visualizations and alerts.

Follow these critical security rules:

1. Do Not Share It Publicly #

Never paste your API Key into public forums, client-side code (like JavaScript running in a browser), or public code repositories (like a public GitHub project). It should only exist in secure, server-side environments.

2. Use Environment Variables #

When writing scripts or applications that connect to Twinnoverse, do not hard-code the API Key directly in your code. Instead, store it in a secure environment variable or a secrets management system (like Docker Secrets, Kubernetes Secrets, or a cloud provider’s secret manager).

Bad (Hard-coded in Python):

<em># DON'T DO THIS</em>
api_key = "your_unique_api_key_goes_here"
headers = {"Authorization": f"Bearer {api_key}"}

<em># DON'T DO THIS</em>
api_key = "your_unique_api_key_goes_here"
headers = {"Authorization": f"Bearer {api_key}"}

Good (Using Environment Variables in Python):

import os

<em># The key is stored securely outside the code</em>
api_key = os.getenv("TWINNOVERSE_API_KEY")
headers = {"Authorization": f"Bearer {api_key}"}

import os

<em># The key is stored securely outside the code</em>
api_key = os.getenv("TWINNOVERSE_API_KEY")
headers = {"Authorization": f"Bearer {api_key}"}

3. Limit Who Has Access #

Only give the API Key to developers or systems that absolutely need it to perform their function. The fewer places it exists, the more secure it is.

What If My API Key is Compromised? #

If you suspect your API Key has been leaked or compromised, you should take immediate action.

Current Action:

1. Delete the Datasource: The most secure action is to delete the compromised datasource entirely from the Twinnoverse dashboard.
2. Create a New One: Create a new datasource. This will generate a new, secure API Key.
3. Update Your Systems: Update all your applications and scripts with the new API Key and Ingestion URL.

(In the future, a “Regenerate API Key” feature may be added to simplify this process without requiring the deletion of the entire datasource.)