API Authentication

How to authenticate your requests to the PDF Hub REST API.

Overview

Every request to the PDF Hub API must include two authentication headers: X-Api-Key and X-Api-Secret. These credentials identify your account and authorize access to the API endpoints. Requests without valid credentials will be rejected with a 401 Unauthorized response.

Getting API Keys

To obtain your API credentials:

1. Sign in to your Mapsoft PDF Hub account.
2. Navigate to Account › API Keys from the user menu.
3. Click Generate New Key Pair to create a new API key and secret.
4. Copy both values immediately — the secret is only shown once at creation time.

Required Headers

Include both headers on every API request:

Header	Description	Example
X-Api-Key	Your public API key identifier.	pk_live_abc123def456
X-Api-Secret	Your private API secret. Keep this confidential.	sk_live_789ghi012jkl

Example Request

Here is a complete authenticated request to the convert endpoint:

POST /api/pdf/convert HTTP/1.1
Host: pdf.mapsoft.com
X-Api-Key: pk_live_abc123def456
X-Api-Secret: sk_live_789ghi012jkl
Content-Type: multipart/form-data; boundary=----FormBoundary

------FormBoundary
Content-Disposition: form-data; name="file"; filename="document.docx"
Content-Type: application/octet-stream

(binary file data)
------FormBoundary--

Error Responses

If authentication fails, the API returns one of the following responses:

Missing headers (401)

Returned when one or both authentication headers are absent from the request.

{
    "error": "Authentication required",
    "message": "Both X-Api-Key and X-Api-Secret headers are required.",
    "statusCode": 401
}

Invalid credentials (401)

Returned when the API key or secret does not match any active key pair.

{
    "error": "Invalid credentials",
    "message": "The provided API key or secret is invalid.",
    "statusCode": 401
}

Revoked key (401)

Returned when the API key has been revoked by the account owner.

{
    "error": "Key revoked",
    "message": "This API key has been revoked. Generate a new key pair from your account settings.",
    "statusCode": 401
}

Insufficient permissions (403)

Returned when the API key does not have permission for the requested operation.

{
    "error": "Forbidden",
    "message": "Your API key does not have permission to access this endpoint.",
    "statusCode": 403
}

Code Examples

curl

curl -X POST https://pdf.mapsoft.com/api/pdf/convert \
  -H "X-Api-Key: pk_live_abc123def456" \
  -H "X-Api-Secret: sk_live_789ghi012jkl" \
  -F "file=@document.docx" \
  -o output.pdf

Python

import requests

url = "https://pdf.mapsoft.com/api/pdf/convert"
headers = {
    "X-Api-Key": "pk_live_abc123def456",
    "X-Api-Secret": "sk_live_789ghi012jkl"
}

with open("document.docx", "rb") as f:
    files = {"file": ("document.docx", f, "application/octet-stream")}
    response = requests.post(url, headers=headers, files=files)

if response.status_code == 200:
    with open("output.pdf", "wb") as out:
        out.write(response.content)
    print("Conversion successful!")
else:
    print(f"Error {response.status_code}: {response.json()}")

JavaScript (Node.js)

const fs = require("fs");
const FormData = require("form-data");

const form = new FormData();
form.append("file", fs.createReadStream("document.docx"));

const response = await fetch("https://pdf.mapsoft.com/api/pdf/convert", {
    method: "POST",
    headers: {
        "X-Api-Key": "pk_live_abc123def456",
        "X-Api-Secret": "sk_live_789ghi012jkl",
        ...form.getHeaders()
    },
    body: form
});

if (response.ok) {
    const buffer = await response.arrayBuffer();
    fs.writeFileSync("output.pdf", Buffer.from(buffer));
    console.log("Conversion successful!");
} else {
    const error = await response.json();
    console.error(`Error ${response.status}:`, error);
}

Best Practices

• Never expose your API secret in client-side code. Always make API calls from a server-side application or secure backend.
• Use environment variables to store your API key and secret rather than hardcoding them in source files.
• Rotate keys periodically. Generate new key pairs and revoke old ones on a regular schedule.
• Use separate keys for development and production environments.
• Monitor usage from the API Keys page to detect unusual activity.