LogFlux API

The LogFlux API is the primary endpoint for sending log data to LogFlux. It provides a simple, secure REST API for log ingestion with support for standardized syslog-compatible log levels and encrypted payloads.

Base URLs

LogFlux provides customer-specific endpoints to ensure data residency compliance and optimal performance:

Each customer receives a unique subdomain for enhanced security and isolation:

• EU Region: https://[customer-id].ingest.[region].logflux.io/v1
• US Region: https://[customer-id].ingest.[region].logflux.io/v1

Example: https://c12345.ingest.us.logflux.io/v1

Benefits of Customer-Specific URLs

• Enhanced Security: Dedicated subdomain for your organization
• Better Isolation: Logical separation from other customers
• Custom Configuration: Tailored rate limits and settings
• Easier Monitoring: Clear identification in logs and metrics

Authentication

All API requests (except health and version endpoints) require authentication using API keys.

API Key Format

1

Authorization: Bearer lf_your_api_key_here

Key Characteristics:

• Prefix: All keys start with lf_
• Format: lf_ followed by 32 alphanumeric characters
• Example: lf_abcd1234efgh5678ijkl9012mnop3456

Endpoints

Health Check

Check if the service is running.

1

GET /health

Response:

200 OK
Content-Type: text/plain

OK

Version Information

Get API version and compatibility information.

1

GET /version

Response:

1
2
3
4
5
6

{
  "api_version": "v1",
  "service": "logflux-ingestor",
  "supported_versions": ["v1"],
  "deprecated_versions": []
}

Handshake - Initialize

Request the server’s RSA public key to begin secure key exchange.

1
2
3

POST /v1/handshake/init
Authorization: Bearer lf_your_api_key_here
Content-Type: application/json

Request Body:

1
2
3

{
  "api_key": "lf_your_api_key_here"
}

Response:

1
2
3

{
  "public_key": "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA...\n-----END PUBLIC KEY-----"
}

Handshake - Complete

Send your encrypted AES key to establish secure communication.

1
2
3

POST /v1/handshake/complete
Authorization: Bearer lf_your_api_key_here
Content-Type: application/json

Request Body:

1
2
3
4

{
  "api_key": "lf_your_api_key_here",
  "encrypted_secret": "bXlzdXBlcnNlY3JldGFlc2tleWVuY3J5cHRlZHdpdGhyc2FvYWVwc2hhMjU2cGFkZGluZ2FuZGJhc2U2NGVuY29kZWQ="
}

Response:

1
2
3
4

{
  "status": "success",
  "key_uuid": "550e8400-e29b-41d4-a716-446655440000"
}

Important: The encrypted_secret contains your AES-256 key encrypted with RSA-OAEP-SHA256 using the server’s public key.

Ingest Log Entry

Send a log entry to LogFlux after completing the handshake.

1
2
3

POST /v1/ingest
Authorization: Bearer lf_your_api_key_here
Content-Type: application/json

Important: All log entries MUST be encrypted. Complete the handshake before sending logs.

Request Body:

1
2
3
4
5
6
7

{
  "timestamp": "2024-01-15T10:30:45.123Z",
  "node": "web-server-01",
  "loglevel": 7,
  "payload": "YXNkZmdoamts...",
  "key_uuid": "550e8400-e29b-41d4-a716-446655440000"
}

Request Parameters

Log Levels (Syslog Compatible)

Encryption Details

• Algorithm: AES-256-GCM (established via RSA handshake)
• Key Exchange: RSA-OAEP-SHA256 with 4096-bit keys
• Payload Format: Base64(IV[12 bytes] + AES-GCM-encrypted-data)
• Key Management: Session-based with UUID tracking

Success Response:

1
2
3
4
5

{
  "status": "success",
  "message": "Log entry processed successfully",
  "request_id": "req_abc123def456"
}

Batch Ingestion

Submit multiple log entries in a single request for high-volume logging.

1
2
3

POST /v1/batch
Authorization: Bearer lf_your_api_key_here
Content-Type: application/json

Request Body:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

{
  "entries": [
    {
      "timestamp": "2024-01-17T10:30:45.123Z",
      "node": "app-server-01",
      "loglevel": 5,
      "payload": "YXNkZmdoamts...",
      "key_uuid": "550e8400-e29b-41d4-a716-446655440000"
    },
    {
      "timestamp": "2024-01-17T10:30:46.456Z",
      "node": "app-server-01",
      "loglevel": 5,
      "payload": "WFlaZGVmZ2hpams...",
      "key_uuid": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}

Limits: Maximum 100 entries per batch

Error Responses

All errors follow a consistent format:

1
2
3
4
5
6
7
8
9

{
  "status": "error",
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid",
    "details": "API key must start with 'lf_'"
  },
  "request_id": "req_abc123def456"
}

Error Codes

Client Errors (4xx)

Server Errors (5xx)

Rate Limiting

LogFlux implements rate limiting to ensure fair usage:

Limits

Rate Limit Headers

All responses include rate limit information:

1
2
3

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 1705493445

Rate Limit Response

When rate limit is exceeded:

1
2
3
4
5
6
7
8

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "API rate limit exceeded",
    "retry_after": 45
  }
}

HTTP Status: 429 Too Many Requests

CORS Support

The API includes full CORS support for browser-based applications:

1
2
3

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

Example Usage

SDK Recommendation: While the examples below demonstrate the API, for production use we strongly recommend using our official SDKs which provide:

• Automatic handshake and key management
• Secure AES-256-GCM encryption
• Retry logic with exponential backoff
• Connection pooling and batching
• Built-in error handling
• Graceful degradation

cURL

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

curl -X POST https://c12345.ingest.us.logflux.io/v1/ingest \
  -H "Authorization: Bearer lf_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "timestamp": "2024-01-17T10:30:45.123Z",
    "node": "secure-app",
    "loglevel": 4,
    "payload": "YWJjZGVmZ2hpams...base64-encrypted-data...",
    "key_uuid": "550e8400-e29b-41d4-a716-446655440000"
  }'

Batch Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

curl -X POST https://c12345.ingest.us.logflux.io/v1/batch \
  -H "Authorization: Bearer lf_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": [
      {
        "timestamp": "2024-01-17T10:30:45.123Z",
        "node": "app-server-01",
        "loglevel": 7,
        "payload": "YWJjZGVmZ2hpams...base64-encrypted-data...",
        "key_uuid": "550e8400-e29b-41d4-a716-446655440000"
      },
      {
        "timestamp": "2024-01-17T10:30:46.456Z",
        "node": "app-server-01",
        "loglevel": 5,
        "payload": "WFlaZGVmZ2hpams...base64-encrypted-data...",
        "key_uuid": "550e8400-e29b-41d4-a716-446655440000"
      }
    ]
  }'

Best Practices

1. Timestamp Handling

• Always include timezone information
• Use UTC timestamps when possible
• Format: YYYY-MM-DDTHH:mm:ss.sssZ

2. Error Handling

• Implement exponential backoff for retries
• Honor retry_after values in rate limit responses
• Log failed requests for debugging

3. Batch Processing

• Use batch endpoints for high-volume logging
• Limit batch size to 100 entries
• Include diverse log levels in batches

4. Encryption

• Complete handshake before sending logs
• Cache key_uuid for subsequent requests
• Generate unique IV for each message
• Never send unencrypted payloads
• Re-handshake if key errors occur

5. Performance

• Reuse HTTP connections when possible
• Implement client-side queuing for resilience
• Monitor rate limit headers

Security Considerations

Transport Security

• All communication must use HTTPS
• Minimum TLS version: 1.2
• Certificate validation required

API Key Security

• Never log API keys
• Rotate keys periodically
• Use environment variables for key storage

Payload Security

• All payloads must be encrypted
• Complete RSA handshake to establish AES keys
• Use AES-256-GCM with session keys
• Generate unique IV for each message
• Track key_uuid for proper decryption

API Versioning

LogFlux uses URL path versioning to ensure backward compatibility. The current version is v1. When new versions are released:

• Existing versions will continue to work
• Deprecation notices will be provided well in advance
• Version information is available via the /version endpoint
• Breaking changes require new major version