Every conversion request to ConvertAPI must be authenticated using Bearer Authentication.

ConvertAPI supports two authentication methods:

• API Tokens - used to authenticate conversion requests
• JWT Tokens (self-signed or generated via API)
• Master Token - used to authenticate administrative endpoints, like user information, consumption, statistics, etc.

All authentication is handled via the Authorization header.

Where to Create API Tokens

You can create and manage your API Tokens in your ConvertAPI dashboard:

https://www.convertapi.com/a/authentication

From this page you can:

• Generate new API Tokens
• Set environment separation (Production / Development)
• Configure usage limits
• View your Key Identifier (Kid)
• Access your API Token secret (used for JWT signing)

Authentication Methods

API Token

API Tokens are the simplest way to authenticate your requests.

They:

• Authenticate conversion requests
• Allow environment separation
• Support consumption limits
• Work immediately without additional configuration

Example Using API Token

curl -X POST https://v2.convertapi.com/convert/docx/to/pdf \
  -H "Authorization: Bearer your_api_token" \
  -F "File=@/path/to/my_file.docx" \

JWT Token (Advanced Security)

JWT Tokens provide enhanced security through:

• Time-based expiration
• IP address restriction
• Stateless authentication
• Reduced risk of token misuse

JWT tokens can be:

• Generated via ConvertAPI JWT endpoint
• Self-signed using your API Token secret

Master Token (Administrative Tasks)

The Master Token is available for Administrator and Owner roles only. It allows users to access their administrative REST-API endpoints, like:

• User information
• Current consumption
• Statistics and logs

There is only one Master token per account. If a Master Token is compromised or exposed, it can be refreshed at any time. Once refreshed, the previous token is immediately invalidated and will no longer have access to any administrative endpoints.

Authorization Header

All requests must include:

Authorization: Bearer YOUR_API_OR_JWT_TOKEN

Authentication Response Codes

JWT Token Generation API

Generate JWT tokens programmatically using your API Token.

Endpoint

POST https://v2.convertapi.com/token/jwt

Headers

Authorization: Bearer your_api_token
Content-Type: application/json

Request Payload

{
  "Kid": "1fbde8c8-df21-457d-8b8a-3e24ee42a823",
  "ExpiresInSec": 3600,
  "ClientIp": "localhost,197.0.0.1"
}

Parameters

cURL Example

curl -X POST https://v2.convertapi.com/token/jwt \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_token" \
  -d '{
    "Kid": "1fbde8c8-df21-457d-8b8a-3e24ee42a825",
    "ExpiresInSec": 3600,
    "ClientIp": "localhost,197.0.0.1"
  }'

Self-Signed JWT Tokens

You may generate JWT tokens locally using your API Token secret.

JWT Payload Structure

{
  "kid": "1fbde8c8-df21-457d-8b8a-3e24ee42a823",
  "exp": 1748344522,
  "iat": 1748344502,
  "nbf": 1748344502,
  "clientIp": "localhost,197.0.0.1"
}

Required Fields

Optional Fields

Signing Requirements

• Use HS256 algorithm
• Sign the token using your API Token secret
• Include the generated JWT in the Authorization header

Using Self-Signed JWT in API Calls

curl -X POST https://v2.convertapi.com/convert/docx/to/pdf \
  -H "Authorization: Bearer your_jwt_token" \
  -F "File=@/path/to/file.docx"

When to Use API Token vs JWT