> ## Documentation Index
> Fetch the complete documentation index at: https://docs.logfleet.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Understanding LogFleet authentication methods

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:

<CodeGroup>
  ```bash Register theme={null}
  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"
    }'
  ```

  ```bash Login theme={null}
  curl -X POST https://api.logfleet.io/api/v1/auth/login \
    -H "Content-Type: application/json" \
    -d '{
      "email": "admin@acme.com",
      "password": "SecureP@ssw0rd!"
    }'
  ```
</CodeGroup>

Response:

```json theme={null}
{
  "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:

```bash theme={null}
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:

<Steps>
  <Step title="Request Reset">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Reset Password">
    Use the token from the email to set a new password:

    ```bash theme={null}
    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!"
      }'
    ```
  </Step>
</Steps>

## 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:

```bash theme={null}
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:

```json theme={null}
{
  "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"
}
```

<Warning>
  The `raw_key` is only shown once at creation time. Store it securely—it cannot be retrieved later.
</Warning>

### 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:

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="List Keys" icon="list">
    ```bash theme={null}
    curl -X GET https://api.logfleet.io/api/v1/api-keys \
      -H "Authorization: Bearer $TOKEN"
    ```
  </Card>

  <Card title="Revoke Key" icon="ban">
    ```bash theme={null}
    curl -X DELETE https://api.logfleet.io/api/v1/api-keys/{id} \
      -H "Authorization: Bearer $TOKEN"
    ```
  </Card>
</CardGroup>

## Security Best Practices

<AccordionGroup>
  <Accordion title="Rotate API Keys Regularly">
    Create new API keys periodically and revoke old ones. This limits exposure if a key is compromised.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="Secure Token Storage">
    Never commit tokens or API keys to version control. Use environment variables or secret management systems.
  </Accordion>

  <Accordion title="Monitor API Key Usage">
    Regularly review your API keys and revoke any that are no longer in use.
  </Accordion>
</AccordionGroup>

## Error Responses

### 401 Unauthorized

Returned when authentication fails:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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