Authentication

Authentication Methods

The ConvertAPI supports the URL Parameters and Basic Authentication stateless authentication methods.

URL Parameters

curl -X GET https://v2.convertapi.com/user?Secret=your-api-secret

Basic Authentication

curl -X GET https://v2.convertapi.com/user -u "your_api_key:your_api_secret" 

The -u or --user flag is a shorthand for the basic authorization header.

If you want to gain full control over the request, you can authenticate it using the "Authorization: Basic your_base64_credentials" header explicitly. The "your_base64_credentials" variable is your_api_key:your_api_secret string encoded in a Base64 format.

The cURL command with an explicit Authorization header would look like this:

curl -X GET https://v2.convertapi.com/user -H 'Authorization: Basic YXBpX2tleTpzZWNyZXQ='

Authentication Credentials

The ConvertAPI REST API supports three authentication credentials:

• Secret - can authenticate requests from the code that is not accessible to the user (server-side software like PHP). Also used to create tokens.
• Token - can authenticate requests from the code accessible for the user (client-side software like JavaScript), has access count and lifetime.
• ApiKey - is used for basic authentication and self-generated tokens.

Api Secret, Api Key, and Tokens can be found in Control Panel.

Secret

The secret is static, and only one secret per account is provided. You can reset it and generate a new one if publicly exposed. Access your secret from Control Panel. The secret is used for all REST API endpoints authentications.

Token

The tokens can be created and deleted from access tokens control panel or REST API. Tokens are more advanced than secret, and you can have as many tokens as you want for staging, pre-production, or production. In addition, you can control token lifetime by setting usage count and lifetime.

Create Token

The token request accepts URL query parameters. In order to make a virtually non-expiring token that can be used instead of a secret key to authenticate your requests, simply set the Lifetime and RequestCount to it's highest values.

• Secret - your API secret key.
• RequestCount - restrict how many requests can be made using a single token. The default is 1, and the maximum can be set to 999999999 requests.
• Lifetime - the token lifetime in seconds. The default is 3600 seconds (1h), and the maximum can be set to 315569520 seconds (10 years).
• Count - specify how many tokens will be created by the request. The default is 1 token.

curl -X POST "https://v2.convertapi.com/token/create?Secret=your-api-secret&RequestCount=3&Lifetime=10000&Count=2"

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

Token usage

curl -X POST "https://v2.convertapi.com/convert/docx/to/pdf?Token=your_token" \
    -H "Content-Type: multipart/form-data; boundary=WebAppBoundary" \
    -F "file=@C:\document.docx;filename=document.docx;type=*/*" 

Delete token

You can leave the token to expire or delete it right away. Please note: your secret key must be provided in the delete request to prevent malicious requests.

curl -X DELETE "https://v2.convertapi.com/token/u3XmwBoA?Secret=your-api-secret"

JWT Token

JWT tokens are dynamically created and signed by secret and not requires access to the ConvertAPI server to create a token.

Create Token

Payload parameters

• Id - random 8 bytes alphanumeric string.
• RequestCount - request count that can be made using this token.
• ValidUntil - token expiration time in Unix timestamp format.
• UserIp - IP address that can use this token (leave blank if you don’t want to restrict).
• ApiKey - your apikey.

The JWT token must by signed by secret.

Header

{
  "alg": "HS256",
  "typ": "JWT"
}

Payload

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

Generate JWT Token Online

Token usage

curl -X POST "https://v2.convertapi.com/convert/docx/to/pdf" \
    -H "Authentication: 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 Authentication failure.

  • 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 passed.
  • 4014 User inactive.