Authentication

LogFleet uses two authentication methods depending on your use case:

Method	Use Case	Header Format
JWT Token	Dashboard, user operations	`Authorization: Bearer {token}`
API Key	Edge agents	`X-API-Key: {key}`

JWT Token Authentication

JWT tokens are used for all user-facing operations: managing agents, viewing dashboards, configuring metrics, and accessing billing information.

Obtaining a Token

Tokens are returned when you register or log in:

curl -X POST https://api.logfleet.io/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "organization_name": "Acme Corp",
    "email": "admin@acme.com",
    "password": "SecureP@ssw0rd!",
    "name": "John Doe"
  }'

curl -X POST https://api.logfleet.io/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@acme.com",
    "password": "SecureP@ssw0rd!"
  }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 86400,
  "user": {
    "id": "616402b3-d4a2-446a-a727-415edc25d175",
    "email": "admin@acme.com",
    "name": "John Doe",
    "role": "admin"
  },
  "organization": {
    "id": "1bbd15d5-c42a-4659-a873-a76092f9ee3b",
    "name": "Acme Corp"
  }
}

Using the Token

Include the token in the Authorization header for all authenticated requests:

curl -X GET https://api.logfleet.io/api/v1/agents \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Token Expiration

Tokens expire after 24 hours by default
The expires_in field in the response indicates seconds until expiration
When a token expires, users must log in again to obtain a new token

Password Reset

If you forget your password:

Request Reset

curl -X POST https://api.logfleet.io/api/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@acme.com"}'

A reset link will be sent to your email.

Reset Password

Use the token from the email to set a new password:

curl -X POST https://api.logfleet.io/api/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "reset-token-from-email",
    "new_password": "NewSecureP@ssw0rd!"
  }'

API Key Authentication

API keys are designed for edge agents. They provide long-lived, scoped credentials that don’t require user interaction to refresh.

Creating an API Key

Use a JWT token to create API keys:

curl -X POST https://api.logfleet.io/api/v1/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Edge Agents",
    "permissions": ["edge:register", "edge:heartbeat", "edge:metrics", "edge:stream"]
  }'

Response:

{
  "api_key": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production Edge Agents",
    "key_prefix": "lf_prod_",
    "permissions": ["edge:register", "edge:heartbeat", "edge:metrics", "edge:stream"],
    "created_at": "2024-01-15T10:00:00Z"
  },
  "raw_key": "lf_prod_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456"
}

The raw_key is only shown once at creation time. Store it securely—it cannot be retrieved later.

Available Permissions

Permission	Description
`edge:register`	Register new edge agents
`edge:heartbeat`	Send heartbeat signals
`edge:metrics`	Push metrics to the platform
`edge:stream`	Stream logs to the cloud

Using API Keys

Edge agents include the API key in the X-API-Key header:

curl -X POST https://api.logfleet.io/api/v1/edge/register \
  -H "X-API-Key: lf_prod_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "edge-location-01",
    "metadata": {
      "location": "warehouse-nyc",
      "version": "1.2.0"
    }
  }'

Managing API Keys

List Keys

curl -X GET https://api.logfleet.io/api/v1/api-keys \
  -H "Authorization: Bearer $TOKEN"

Revoke Key

curl -X DELETE https://api.logfleet.io/api/v1/api-keys/{id} \
  -H "Authorization: Bearer $TOKEN"

Security Best Practices

Rotate API Keys Regularly

Create new API keys periodically and revoke old ones. This limits exposure if a key is compromised.

Use Minimal Permissions

Only grant the permissions each edge agent actually needs. If an agent only sends heartbeats and metrics, don’t include edge:stream.

Secure Token Storage

Never commit tokens or API keys to version control. Use environment variables or secret management systems.

Monitor API Key Usage

Regularly review your API keys and revoke any that are no longer in use.

Error Responses

401 Unauthorized

Returned when authentication fails:

{
  "error": "unauthorized",
  "message": "Invalid or expired token"
}

Common causes:

Token has expired
Token is malformed
API key has been revoked
Missing authentication header

403 Forbidden

Returned when authenticated but lacking permission:

{
  "error": "forbidden",
  "message": "Insufficient permissions for this operation"
}

Common causes:

API key missing required permission
User role doesn’t allow the operation
Accessing resources from another organization

Getting Started

Concepts

JWT Token Authentication

Obtaining a Token

Using the Token

Token Expiration

Password Reset

API Key Authentication

Creating an API Key

Available Permissions

Using API Keys

Managing API Keys

List Keys

Revoke Key

Security Best Practices

Error Responses

401 Unauthorized

403 Forbidden

​JWT Token Authentication

​Obtaining a Token

​Using the Token

​Token Expiration

​Password Reset

​API Key Authentication

​Creating an API Key

​Available Permissions

​Using API Keys

​Managing API Keys

List Keys

Revoke Key

​Security Best Practices

​Error Responses

​401 Unauthorized

​403 Forbidden

JWT Token Authentication

Obtaining a Token

Using the Token

Token Expiration

Password Reset

API Key Authentication

Creating an API Key

Available Permissions

Using API Keys

Managing API Keys

Security Best Practices

Error Responses

401 Unauthorized

403 Forbidden