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

# Overview

> Authenticate with the Lofty API using OAuth 2.0 or API keys.

All API requests require authentication via the `Authorization` header.

| Method        | Header format           | Best for                                    |
| ------------- | ----------------------- | ------------------------------------------- |
| **OAuth 2.0** | `Bearer <access_token>` | Multi-tenant apps, third-party integrations |
| **API Key**   | `token <api_key>`       | Personal automation, scripts, CLI           |

## Which method should I use?

| Scenario                      | Method    | Grant Type                                         |
| ----------------------------- | --------- | -------------------------------------------------- |
| CLI tool (`lofty-cli`)        | API Key   | Used as `LOFTY_CUSTOMER_KEY` in Client Credentials |
| Personal scripts / automation | API Key   | Direct `token` header                              |
| Server-to-server (no user)    | OAuth 2.0 | Client Credentials + `customer_key`                |
| Web app (user authorizes)     | OAuth 2.0 | Authorization Code                                 |
| SPA / mobile app              | OAuth 2.0 | Authorization Code + PKCE                          |
| Multi-tenant SaaS platform    | OAuth 2.0 | Authorization Code                                 |

<CardGroup cols={2}>
  <Card title="OAuth 2.0" icon="shield-check" href="/authentication/oauth2">
    Three grant types: Authorization Code, PKCE, and Client Credentials. Scoped permissions with security review.
  </Card>

  <Card title="API Keys" icon="key" href="/authentication/api-keys">
    User-scoped personal access tokens. Configurable expiration and `THIRD_PARTY_OPERATION` scope.
  </Card>
</CardGroup>

## Base URL

```
https://api.lofty.com
```

## Request format

```bash theme={null}
curl https://api.lofty.com/v1.0/leads \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>"
```

Or via CLI:

```bash theme={null}
lofty-cli leads list --limit 10
```

## Rate limiting

Rate limits are **per-app** (not per-account), configured on each registered application.

| App Mode    | Rate Limit       |
| ----------- | ---------------- |
| Development | 100 requests/min |
| Production  | 500 requests/min |

The window resets every **60 seconds**. Every response includes rate limit headers:

| Header                  | Description                                     |
| ----------------------- | ----------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the current window  |
| `X-RateLimit-Remaining` | Requests remaining in the current window        |
| `X-RateLimit-Reset`     | Time (UTC epoch seconds) when the window resets |

When the limit is exceeded, the API returns `HTTP 429`:

```http theme={null}
HTTP/1.1 429
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 21000
{"message":"Too Many Requests"}
```

<Note>
  Some endpoints (e.g. AI features) have lower per-endpoint limits. Check the `X-RateLimit-Limit` header in responses to determine the actual limit.
</Note>

## Common errors

| HTTP Status | Code     | Description                                                                                                                                                                         |
| ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401`       | —        | Invalid or missing authentication credentials.                                                                                                                                      |
| `403`       | `200100` | Token is valid but lacks the required permission scope. Grant the scope in the [Developer Portal](https://api.lofty.com/vendor/frontend/static/index.html#/login) and re-authorize. |
| `429`       | —        | Rate limit exceeded. Retry with backoff.                                                                                                                                            |

See [Error Codes](/authentication/error-codes) for the full reference.