Authentication - Poesius API Documentation

Getting Your API Token

Log in to the Web App: Visit https://app.poesius.com and sign in
Navigate to API Keys: Go to your account settings or API keys section
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

X-API-Key: pk_your_api_key_here

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

Using Authentication

REST API Example

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:

{
  "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:

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:

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

Important: Save the key value immediately - it’s only shown once and cannot be retrieved later!

Authentication Methods

The API supports multiple authentication methods:

1. API Key (Recommended for Automation)

X-API-Key: pk_your_api_key_here

This is the recommended method for programmatic access and automation.

2. JWT Bearer Token

Authorization: Bearer <jwt_token>

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

3. OAuth 2.1 Bearer Token

Authorization: Bearer <oauth_token>

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.

Troubleshooting

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

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.

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.

​Getting Your API Token

​Authentication Methods

​API Key Authentication

​Using Authentication

​REST API Example

​MCP Example

​Creating an API Key via API

​Authentication Methods

​1. API Key (Recommended for Automation)

​2. JWT Bearer Token

​3. OAuth 2.1 Bearer Token

​Troubleshooting

Getting Your API Token

Authentication Methods

API Key Authentication

Using Authentication

REST API Example

MCP Example

Creating an API Key via API

Authentication Methods

1. API Key (Recommended for Automation)

2. JWT Bearer Token

3. OAuth 2.1 Bearer Token

Troubleshooting