Sign up
Documentation menu

Authentication

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

ConvertAPI supports two authentication methods for conversion requests:

  • API Tokens - used to authenticate conversion requests
  • JWT Tokens (self-signed or generated via API)

In addition, a Master Token authenticates administrative endpoints, like user information, consumption, statistics, etc.

All authentication is handled via the Authorization header, with a query parameter fallback for links that cannot set headers (see Query Parameter Authentication).

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

Query Parameter Authentication

When a request cannot carry headers - for example a plain download link or URL-based conversions - pass your API Token as the Token query parameter instead:

https://v2.convertapi.com/convert/web/to/pdf?Token=your_api_token&Url=https%3A%2F%2Fexample.com

The legacy Secret and Auth query parameters are accepted as aliases of Token. Prefer the Authorization header whenever possible, so tokens do not end up in logs, proxies, or browser history.

Authentication Response Codes

Status Code Description
200 OK Request authenticated successfully
401 Unauthorized Invalid or missing API credentials
403 Forbidden No conversions remaining. Upgrade your plan or purchase more conversions

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,198.51.100.1"
}

Parameters

Field Type Required Description
Kid string (GUID) Yes Key identifier from your dashboard
ExpiresInSec integer Yes Token expiration time in seconds
ClientIp string No Restrict token usage to specific IP addresses

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,198.51.100.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,198.51.100.1"
}

Required Fields

Field Description
kid Key identifier from dashboard
exp Expiration timestamp (Unix time)

Optional Fields

Field Description
iat Issued at time
nbf Not valid before time
clientIp Restrict token to specific IP(s)

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

Use Case Recommended Method
Simple server-to-server integration API Token
Frontend or distributed systems JWT
IP-restricted access JWT
Short-lived secure access JWT