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

# Authentication

> Learn how to authenticate with the Poesius API

## Getting Your API Token

1. **Log in to the Web App**: Visit `https://app.poesius.com` and sign in
2. **Navigate to API Keys**: Go to your account settings or API keys section
3. **Create an API Key**:
   * Click "Create API Key"
   * Provide a name (e.g., "automation-key")
   * Optionally add a description
   * **Important**: Copy the key immediately - it's only shown once!

## Authentication Methods

The API uses API keys for authentication. API keys are created and managed through the web app at `https://app.poesius.com`.

### API Key Authentication

```http theme={null}
X-API-Key: pk_your_api_key_here
```

<Info>
  API keys are the recommended authentication method for all API requests. They provide secure, long-term access without requiring session management.
</Info>

## Using Authentication

### REST API Example

```bash theme={null}
curl -X POST "https://poe.poesius.com/api/v1/slides/generate-from-doc" \
  -H "X-API-Key: pk_your_api_key_here" \
  -F "document=@document.pdf"
```

### MCP Example

MCP uses the same API key authentication:

```json theme={null}
{
  "headers": {
    "X-API-Key": "pk_your_api_key_here"
  },
  "method": "tools/call",
  "params": {
    "name": "generate_slides",
    "arguments": {}
  }
}
```

## Creating an API Key via API

If you already have a JWT token (from the web app), you can create an API key programmatically:

```bash theme={null}
curl -X POST "https://poe.poesius.com/api/v1/api-keys/" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "automation-key",
    "description": "For slide generation from documents"
  }'
```

**Response:**

```json theme={null}
{
  "id": "uuid",
  "name": "automation-key",
  "key": "pk_...",
  "description": "For slide generation from documents",
  "is_active": true,
  "created_at": "2024-01-01T00:00:00Z"
}
```

<Warning>
  **Important**: Save the `key` value immediately - it's only shown once and cannot be retrieved later!
</Warning>

## Authentication Methods

The API supports multiple authentication methods:

### 1. API Key (Recommended for Automation)

```http theme={null}
X-API-Key: pk_your_api_key_here
```

This is the recommended method for programmatic access and automation.

### 2. JWT Bearer Token

```http theme={null}
Authorization: Bearer <jwt_token>
```

<Info>
  JWT tokens are managed by the frontend web application. For programmatic access, use API keys instead.
</Info>

### 3. OAuth 2.1 Bearer Token

```http theme={null}
Authorization: Bearer <oauth_token>
```

<Info>
  OAuth authentication requires a visual login flow through the web platform. This is not suitable for headless automation as it requires user interaction with a browser.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication Error">
    If you receive an authentication error, verify:

    * Your API key is correct and active
    * The key is included in the request headers as `X-API-Key`
    * The API key hasn't been revoked in the web app
  </Accordion>

  <Accordion title="API Key Management">
    API keys don't expire automatically. You can revoke or create new keys anytime in the web app at `https://app.poesius.com`.
  </Accordion>

  <Accordion title="Multiple Authentication Methods">
    The API supports API keys, JWT tokens, and OAuth 2.1 tokens. API keys are recommended for automation, while OAuth is suitable for applications that can redirect users to login.
  </Accordion>
</AccordionGroup>