Articles on: Documentation


ConvertAPI Authentication Methods

ConvertAPI supports URL Parameters and Bearer Authentication for stateless authentication.


URL ParametersStatelessSecret, Token
Bearer AuthenticationStatelessSecret, Token, JWT Token

URL Parameters Authentication

Authenticate by including your secret key or token as a URL parameter:

Using Secret

curl -X GET

Using Token

curl -X GET

Bearer Authentication

Authenticate using your Secret, Token, or JWT Token as a bearer token:

Using Secret

curl -X GET -H 'Authorization: Bearer your_api_secret'

Using Token

curl -X GET -H 'Authorization: Bearer your_token'

Using JWT Token

curl -X GET -H 'Authorization: Bearer your_jwt_token'

Authentication Credentials

ConvertAPI REST API supports three types of authentication credentials:

- Secret: For server-side applications. Each account has one unique secret key. Also used to create tokens.
- Token: For client-side and server-side applications. Includes access count and lifetime restrictions. Tokens must be created in your account.
- JWT Token: For bearer authentication. JWT tokens can be created on the fly without accessing your account.

Find your API Secret, API Key, and Tokens in the Control Panel.


Your secret key is static and unique to your account. It can be reset if exposed. Access it from the Control Panel. Use your secret key for all REST API endpoint authentications.

Token Management

Tokens offer advanced control with features like staging and production environments. They can be managed via the Access Tokens Control Panel or REST API. Note that token management (creation and deletion) can only be performed using secret authentication.

Create Token

Create a token with specific attributes:

- Secret: Your API secret key.
- RequestCount: Maximum requests per token (default 1, max 999999999).
- Lifetime: Token lifetime in seconds (default 3600, max 315569520).
- Count: Number of tokens to create (default 1).

curl -X POST ""


    "Tokens": [
        { "Id": "4X4RxBGP", "ValidUntil": "2017-08-22T16:45:24.6184076Z" },
        { "Id": "mKRuP5zW", "ValidUntil": "2017-08-22T16:45:24.6184076Z" }

Token Usage

Use the token for API requests:

curl -X POST "" \
    -H "Content-Type: multipart/form-data; boundary=WebAppBoundary" \
    -F "file=@C:\document.docx;filename=document.docx;type=*/*"

Delete Token

Tokens can expire or be deleted immediately. Provide your secret key in the delete request for security:

curl -X DELETE ""

JWT Token

JWT tokens are signed with your secret and do not require server access to create. JWT tokens are only supported for Bearer Authentication.

Create JWT Token

Payload parameters:

- Id: Random 8-byte alphanumeric string.
- RequestCount: Number of allowed requests.
- ValidUntil: Expiration time in Unix timestamp format.
- UserIp: IP restriction (optional).
- ApiKey: Your API key.

Sign the JWT token with your secret.


  "alg": "HS256",
  "typ": "JWT"


  "Id": "8A4MpB1P",
  "RequestCount": 1,
  "ValidUntil": 1699419101,
  "UserIp": "",
  "ApiKey": "your_api_key"

Generate JWT Token Online

JWT Token Usage

Use the JWT token in your API request:

curl -X POST "" \
    -H "Authorization: Bearer your_jwt_token" \
    -H "Content-Type: multipart/form-data; boundary=WebAppBoundary" \
    -F "file=@C:\document.docx;filename=document.docx;type=*/*"

HTTP Response Codes

- 200 OK
- 2000: Token created successfully.
- 2001: Token deleted successfully.
- 401 Unauthorized
- 4010: Invalid user credentials - bad secret.
- 4011: Invalid user credentials - bad token.
- 4012: Invalid user credentials - bad JWT token.
- 4013: User credentials not set - secret or token must be provided.
- 4014: User inactive.

Updated on: 23/07/2024

Was this article helpful?

Share your feedback


Thank you!