Articles on: Documentation

Authentication

ConvertAPI Authentication Methods



ConvertAPI supports URL Parameters and Bearer Authentication for stateless authentication.

Overview



MethodPersistenceUsage
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 https://v2.convertapi.com/user?Secret=your-api-secret


Using Token



curl -X GET https://v2.convertapi.com/user?Token=your_token



Bearer Authentication



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

Using Secret



curl -X GET https://v2.convertapi.com/user -H 'Authorization: Bearer your_api_secret'


Using Token



curl -X GET https://v2.convertapi.com/user -H 'Authorization: Bearer your_token'


Using JWT Token



curl -X GET https://v2.convertapi.com/user -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.

Secret



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



Use the token for API requests:

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



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

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



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.

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

JWT Token Usage



Use the JWT token in your API request:

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

Cancel

Thank you!