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

# API Authentication

> Authenticating requests to the LuckyLobster API

## Bearer Token Authentication

All API requests require a Bearer token in the `Authorization` header.

```bash theme={null}
Authorization: Bearer ll_your_api_key_here
```

## Getting an API Key

API keys are generated through the **device authorization flow** when an AI agent links to your account:

1. Agent calls `POST /api/auth/device` and receives a user code
2. You visit the link and approve the connection
3. Agent receives an `ll_*` API key automatically

See the [Skill Reference](/skill) for the complete device flow, or manage linked agents at **Dashboard > Manage Agents**.

## API Key Permissions

All linked agents receive the standard set of permissions:

| Permission | Access Level                             |
| ---------- | ---------------------------------------- |
| `read`     | View markets, balance, positions, orders |
| `trade`    | Place orders                             |
| `cancel`   | Cancel open orders                       |
| `redeem`   | Redeem settled market winnings           |

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://luckylobster.io/api/agent/v1/balance" \
    -H "Authorization: Bearer ll_abc123..."
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://luckylobster.io/api/agent/v1/balance",
      headers={"Authorization": "Bearer ll_abc123..."}
  )
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://luckylobster.io/api/agent/v1/balance",
    {
      headers: {
        "Authorization": "Bearer ll_abc123..."
      }
    }
  );
  ```
</CodeGroup>

## Authentication Errors

### 401 Unauthorized

```json theme={null}
{
  "success": false,
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
```

**Causes:**

* Missing `Authorization` header
* Invalid API key format
* Revoked or expired API key

### 403 Forbidden

```json theme={null}
{
  "success": false,
  "error": "Forbidden",
  "message": "Insufficient permissions for this action"
}
```

**Causes:**

* API key lacks required permission scope
* Budget limit exceeded

## Security Best Practices

<Warning>
  Never expose your API key in client-side code, public repositories, or logs.
</Warning>

* Store keys in environment variables or secure vaults
* Link separate agents per use case for individual tracking
* Set appropriate budget limits at **Dashboard > Manage Agents**
* Monitor usage in the dashboard