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

# Authentication

> User authentication and API key management

## Overview

LuckyLobster uses two authentication systems:

1. **User Authentication** - For accessing the dashboard (email/password, social login, passkeys)
2. **API Key Authentication** - For agent/programmatic access to the trading API

## User Authentication

### Supported Methods

<CardGroup cols={2}>
  <Card title="Email & Password" icon="envelope">
    Traditional email/password with optional 2FA
  </Card>

  <Card title="Social Login" icon="share-nodes">
    Google, GitHub, and more
  </Card>

  <Card title="Passkeys" icon="fingerprint">
    Biometric authentication (Face ID, Touch ID, Windows Hello)
  </Card>
</CardGroup>

### Two-Factor Authentication (2FA)

We strongly recommend enabling 2FA for additional security:

1. Go to **Dashboard > Settings > Security**
2. Click **Enable 2FA**
3. Scan the QR code with your authenticator app (Google Authenticator, Authy, etc.)
4. Enter the verification code to confirm

<Warning>
  Save your 2FA backup codes in a secure location. You'll need them if you lose access to your authenticator app.
</Warning>

## API Key Authentication

### How API Keys Are Created

API keys are generated through the **device authorization flow** when an AI agent links to your account. There is no manual "Create API Key" button - instead:

1. Your AI agent initiates the device flow (`POST /api/auth/device`)
2. You visit the link page and enter the code shown by your agent
3. After you approve, the agent receives an `ll_*` API key automatically

Once linked, you manage your agents and their API keys at **Dashboard > Manage Agents**.

<Tip>
  See the [Skill Reference](/skill) for the full device authorization flow, or the [Quickstart](/quickstart) for a step-by-step walkthrough.
</Tip>

### API Key Format

```
ll_abc123xyz789defghi456...
```

* Prefix: `ll_`
* Hash: 64-character secure random string

### Using API Keys

Include your API key in the `Authorization` header:

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

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

  headers = {
      "Authorization": "Bearer ll_your_key_here"
  }

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

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

### Permission Scopes

All linked agents receive the standard set of permissions:

| Scope    | Description            | Endpoints                                  |
| -------- | ---------------------- | ------------------------------------------ |
| `read`   | Read-only access       | Markets, balance, positions, order history |
| `trade`  | Place orders           | POST /orders                               |
| `cancel` | Cancel open orders     | DELETE /orders                             |
| `redeem` | Redeem settled markets | POST /settlements/redeem                   |

### Rate Limiting

API keys are rate limited to protect against abuse:

* **Default**: 100 requests/minute
* **Headers**: Check `X-RateLimit-*` headers in responses

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200
```

When rate limited, you'll receive a `429 Too Many Requests` response:

```json theme={null}
{
  "success": false,
  "error": "Rate Limited",
  "message": "Too many requests. Please wait before retrying.",
  "retryAfter": 30
}
```

### Budget Limits

You can configure spending limits for each agent at **Dashboard > Manage Agents**:

| Setting                | Description                                    |
| ---------------------- | ---------------------------------------------- |
| **Fixed Limit**        | Maximum USDC the agent can spend               |
| **Budget Percent**     | Percentage of wallet balance the agent can use |
| **Max Position Value** | Cap on total open position value               |

Check budget via the API:

```bash theme={null}
curl "https://luckylobster.io/api/agent/v1/budget" \
  -H "Authorization: Bearer ll_..."
```

Response:

```json theme={null}
{
  "success": true,
  "data": {
    "usdc": 46.58,
    "limitedBy": "percent",
    "wallet": 93.16,
    "config": {
      "fixedLimit": null,
      "budgetPercent": 50,
      "maxPositionValue": null,
      "used": 0
    }
  }
}
```

### Revoking API Keys

To revoke an agent's API key:

1. Go to **Dashboard > Manage Agents**
2. Find the agent you want to revoke
3. Click the **Revoke** button
4. Confirm the action

<Warning>
  Revoking a key is immediate and irreversible. Any agents using that key will lose access.
</Warning>

## Security Best Practices

<AccordionGroup>
  <Accordion icon="shield" title="Never expose API keys in client-side code">
    API keys should only be used server-side or in secure agent environments.
    Never include them in browser JavaScript, mobile apps, or public repositories.
  </Accordion>

  <Accordion icon="key" title="Link separate agents for different use cases">
    Each agent gets its own API key through the device flow.
    This gives you individual budget tracking and selective revocation.
  </Accordion>

  <Accordion icon="dollar-sign" title="Use conservative budget limits">
    Start with low budget limits and increase as needed.
    This protects against bugs or unexpected agent behavior.
  </Accordion>

  <Accordion icon="pause" title="Pause agents when not in use">
    Use the pause feature in Manage Agents to temporarily disable an agent
    without revoking its key. You can resume it later.
  </Accordion>
</AccordionGroup>

## Wallet Security

Your Polymarket wallet private key is protected with:

* **AES-256-GCM encryption** at rest
* **Per-wallet unique IV** (initialization vector)
* **Server-side only decryption** during order signing
* **No client-side key exposure**

The encryption key is stored securely in our infrastructure and never exposed in API responses.

## Audit Logging

All sensitive operations are logged:

* Agent linking/revocation
* Order placement
* Wallet operations
* Login attempts

## API Reference

<Card title="Auth Endpoints" icon="lock" href="/api-reference/authentication">
  Full API authentication documentation
</Card>