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

# Authentication

> How to authenticate with the Parsefy API

## API Keys

All requests to the `/v1/extract` endpoint require authentication using an API key.

### Getting an API Key

1. Join the [waitlist](https://parsefy.io)
2. Once approved, you'll receive your API key via email

API keys follow the format: `pk_` followed by a unique identifier.

```
pk_live_xxxxxxxxxxxxxxxxxxxx
```

<Warning>
  Keep your API keys secure. Never expose them in client-side code, public repositories, or logs.
</Warning>

## Using Your API Key

### Bearer Token (Recommended)

Include your API key in the `Authorization` header as a Bearer token:

```bash theme={null}
curl -X POST "https://api.parsefy.io/v1/extract" \
  -H "Authorization: Bearer pk_your_api_key" \
  -F "file=@document.pdf" \
  -F 'output_schema={...}'
```

### SDK Configuration

<Tabs>
  <Tab title="Python">
    **Option 1: Environment Variable (Recommended)**

    ```bash theme={null}
    export PARSEFY_API_KEY=pk_your_api_key
    ```

    ```python theme={null}
    from parsefy import Parsefy

    # Automatically reads PARSEFY_API_KEY
    client = Parsefy()
    ```

    **Option 2: Direct Configuration**

    ```python theme={null}
    from parsefy import Parsefy

    client = Parsefy(api_key="pk_your_api_key")
    ```
  </Tab>

  <Tab title="JavaScript">
    **Option 1: Environment Variable (Recommended)**

    ```bash theme={null}
    export PARSEFY_API_KEY=pk_your_api_key
    ```

    ```typescript theme={null}
    import { Parsefy } from 'parsefy';

    // Automatically reads PARSEFY_API_KEY
    const client = new Parsefy();
    ```

    **Option 2: Direct Configuration**

    ```typescript theme={null}
    import { Parsefy } from 'parsefy';

    const client = new Parsefy('pk_your_api_key');

    // Or with options
    const client = new Parsefy({
      apiKey: 'pk_your_api_key',
      timeout: 120000,
    });
    ```
  </Tab>
</Tabs>

## Authentication Errors

### 401 Unauthorized

Returned when authentication fails:

```json theme={null}
{
  "detail": "Invalid or missing API key"
}
```

**Common causes:**

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

### 403 Forbidden

Returned for the playground endpoint when the request origin is not allowed:

```json theme={null}
{
  "detail": "Origin not allowed"
}
```

## Playground (No Auth)

The `/v1/playground` endpoint allows testing **without an API key**, but with restrictions:

* **Rate Limited**: 10 credits per day per IP
* **Origin Restricted**: Only allowed from authorized domains

The playground is accessible through [parsefy.io](https://parsefy.io).

<Note>
  The playground is designed for testing and demos. For production use, always use an API key with the `/v1/extract` endpoint.
</Note>

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Use Environment Variables" icon="terminal">
    Never hardcode API keys. Use environment variables or secrets managers.
  </Card>

  <Card title="Server-Side Only" icon="server">
    Make API calls from your backend. Never expose keys in frontend code.
  </Card>

  <Card title="Rotate Regularly" icon="rotate">
    Periodically rotate your API keys, especially if you suspect a leak.
  </Card>

  <Card title="Principle of Least Privilege" icon="shield">
    Use separate keys for development and production environments.
  </Card>
</CardGroup>

### Example: Secure Backend Setup

```python theme={null}
# Bad: Hardcoded key
client = Parsefy(api_key="pk_live_xxxxx")

# Good: Environment variable
import os
client = Parsefy(api_key=os.environ["PARSEFY_API_KEY"])

# Better: Auto-load from environment
client = Parsefy()  # Reads PARSEFY_API_KEY automatically
```

### Frontend Architecture

<Warning>
  Never call the Parsefy API directly from browser JavaScript. Always proxy through your own backend to keep your API key secure.
</Warning>