API Keys

API Keys

API keys allow you to interact with the Lumos Gate API programmatically. Each key is scoped to your account and can be used to manage servers, domains, WAF rules, and configurations without the dashboard. API keys are available on Pro and Enterprise plans.

Key Format and Storage

API keys follow this format:

lmsk_<64 hex characters>

For example: lmsk_a1b2c3d4e5f6... (69 characters total).

The lmsk_ prefix makes keys easily identifiable in logs and secret scanners. The key is generated using crypto.randomBytes(32), producing 32 bytes (256 bits) of cryptographic randomness encoded as hex.

Security model: The full API key is never stored in the database. On creation, the key is hashed with SHA-256 and only the hash is persisted. The dashboard displays a truncated prefix (first 12 characters, e.g., lmsk_a1b2c3d4) for identification purposes. The full plaintext key is shown exactly once at creation time -- if you lose it, you must delete the key and create a new one.

Creating an API Key

Via the Dashboard

1. Navigate to Dashboard -> Settings -> API Keys
2. Click Create API Key
3. Enter a descriptive name (e.g., "CI/CD Pipeline", "Terraform", "Monitoring Script")
4. The full API key is displayed. Copy it immediately.
5. Store the key in a secure location (password manager, environment variable, secrets vault)

Via the API

You can also create API keys programmatically if you already have one:

curl -X POST https://app.lumosgate.com/api/settings/api-keys \
  -H "x-api-key: lmsk_your_existing_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "New Key for Staging"}'

Response (HTTP 201):

{
  "id": "key_abc123",
  "name": "New Key for Staging",
  "key": "lmsk_a1b2c3d4e5f6789...",
  "key_prefix": "lmsk_a1b2c3d4",
  "created_at": "2026-02-20T14:30:00.000Z"
}

Warning: The key field in the response is the full plaintext key. This is the only time it will ever be returned. Subsequent GET requests only return the key_prefix.

Limits

• Maximum 10 API keys per account
• Key names must be 100 characters or less
• Key names cannot be empty
• Keys do not expire automatically (you manage their lifecycle manually)

If you attempt to create an 11th key, the API returns HTTP 403 with "Maximum 10 API keys allowed".

Using API Keys

Include your API key in the x-api-key header of every request:

curl -X GET https://app.lumosgate.com/api/servers \
  -H "x-api-key: lmsk_your_key_here"

Example: List All Servers

curl -s https://app.lumosgate.com/api/servers \
  -H "x-api-key: lmsk_your_key_here" | jq .

Example: List All Domains

curl -s https://app.lumosgate.com/api/domains \
  -H "x-api-key: lmsk_your_key_here" | jq .

Example: Create a New Domain

curl -X POST https://app.lumosgate.com/api/domains \
  -H "x-api-key: lmsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "origins": [{"ip": "10.0.1.50", "port": 8080}],
    "serverIds": ["srv_abc123"],
    "sslEnabled": true
  }'

Example: Export Full Configuration

Download your entire Lumos Gate configuration as JSON for backup or migration purposes. See Config Export for the full export format.

curl -s https://app.lumosgate.com/api/settings/export \
  -H "x-api-key: lmsk_your_key_here" \
  -o lumos-backup.json

Example: List API Keys

curl -s https://app.lumosgate.com/api/settings/api-keys \
  -H "x-api-key: lmsk_your_key_here" | jq .

Response:

[
  {
    "id": "key_abc123",
    "name": "CI/CD Pipeline",
    "keyPrefix": "lmsk_a1b2c3d4",
    "lastUsedAt": "2026-02-20T14:30:00.000Z",
    "createdAt": "2026-02-15T10:00:00.000Z"
  },
  {
    "id": "key_def456",
    "name": "Terraform",
    "keyPrefix": "lmsk_e5f6g7h8",
    "lastUsedAt": null,
    "createdAt": "2026-02-18T12:00:00.000Z"
  }
]

Note: The list response only includes the keyPrefix (first 12 characters), never the full key.

Error Responses

If your account is frozen, API keys that perform mutations (POST, PUT, DELETE on resources) will return HTTP 403 with "Account is frozen. Renew your plan to make changes." Read-only operations (GET) continue to work.

Revoking a Key

Via the Dashboard

1. Navigate to Dashboard -> Settings -> API Keys
2. Find the key by its name or prefix
3. Click Delete
4. The key is immediately invalidated

Via the API

curl -X DELETE "https://app.lumosgate.com/api/settings/api-keys?id=key_abc123" \
  -H "x-api-key: lmsk_your_key_here"

Response:

{
  "success": true
}

If the key ID does not exist or does not belong to your account, the API returns HTTP 404 with "API key not found".

Note: Revoking a key does not affect any servers, domains, or configurations. It only removes the authentication credential. Any automation using that key will start receiving 401 errors immediately.

Authentication Flow

When you make an API request with an x-api-key header:

1. The API extracts the key from the header
2. It computes the SHA-256 hash of the provided key
3. It looks up the hash in the api_keys table
4. If a match is found, the request is authenticated as the key's owner
5. If no match is found, HTTP 401 is returned

This means there is no way to recover a lost key from the database -- you must create a new one. The SHA-256 hashing ensures that even if the database is compromised, the actual API keys cannot be extracted.

Security Best Practices

• Never commit API keys to source control. Use environment variables, .env files (in .gitignore), or a secrets manager (AWS Secrets Manager, HashiCorp Vault, 1Password CLI).

• Use descriptive names so you can identify which key is used where and revoke the right one if compromised.

  Good names:
    "GitHub Actions - Production Deploy"
    "Terraform - Staging"
    "Monitoring Script - Grafana"
  
  Bad names:
    "key1"
    "test"
    "my key"

• Rotate keys periodically. Create a new key, update your integrations, then delete the old key. There is no built-in expiration, so rotation is your responsibility.

• Use separate keys for different environments (staging, production) and different integrations (CI/CD, Terraform, monitoring). This limits blast radius if a key is compromised.

• Monitor lastUsedAt. The dashboard shows when each key was last used. Keys that have never been used or have not been used in months may be candidates for deletion.

• Revoke immediately if compromised. If you suspect a key has been leaked (e.g., committed to a public repository), delete it immediately in the dashboard and create a new one. The old key is invalidated instantly.

• Do not share keys between team members. Each person or service should have its own key for auditability.

Next Steps

• Config Export -- Export your full configuration as JSON via the API
• Servers -- Manage servers programmatically
• Domains -- Manage domains and origins programmatically
• WAF -- Manage WAF rules via the API
• Credits & Billing -- Understand frozen account behavior and its effect on API access
• Account -- Manage account settings and deletion
• Architecture -- Understand the security model and token hashing