Connecting to Carbone

Using API Key Authentication

Carbone uses API key authentication via a Bearer token in the Authorization header. To obtain an API key:

Log in to your Carbone account at https://account.carbone.io
Copy the API key shown on the account home page

After obtaining your API key, set the following connection properties:

AuthScheme: Set this to APIKey.
APIKey: Set this to your Carbone API key (Bearer token).
CarboneVersion: (Optional) The major version of the Carbone API to target via the carbone-version request header. Defaults to 5. Accepted values: 5, 4, 3, staging.

Example Connection String

Profile=C:\profiles\Carbone.apip;AuthScheme=APIKey;APIKey=your_api_key;

Connecting to Carbone

Once the authentication is configured, you can connect to Carbone and query data from any of the available tables such as Status, Templates, TemplateCategories, and TemplateTags.

Available Tables

The Carbone API Profile provides access to the following tables:

Status: Retrieve the current operational status and version of the Carbone API server (single-row endpoint; no authentication required)
Templates: List deployed Carbone templates with metadata (VersionId, Name, Category, Origin, timestamps, tags); supports cursor-based pagination and filtering by Id, VersionId, Category, and Origin
TemplateCategories: List all categories assigned to deployed Carbone templates, sorted alphabetically by name
TemplateTags: List all tags applied to deployed Carbone templates, sorted alphabetically by name

Important Notes

All template endpoints require APIKey to be set. The Status endpoint does not require authentication and can be queried with AuthScheme=APIKey.
The Carbone API requires the carbone-version request header. The profile defaults this to 5 (current major version); override via the CarboneVersion connection property if needed.
Timestamp columns (CreatedAt, ExpireAt) are returned as raw UTC Unix timestamps in seconds since epoch (long type). Use SQL date functions to convert when needed.
For non-versioned templates the API returns id as null and populates only versionId; use VersionId as the unique identifier when versioning is disabled.
Templates uploaded with a test API token auto-delete after 30 days. Use a production token for permanent template storage.
Document generation (POST /render) and template upload (POST /template) are not exposed as read-only tables; use the Carbone REST API directly for write operations.
The Templates table supports cursor-based pagination automatically via the nextCursor response field (default page size 100); no manual cursor handling is required.

API Documentation

For more information about the Carbone API, see the official Carbone HTTP API documentation at https://carbone.io/documentation/developer/http-api/introduction.html.

Usage Examples

Status:

SELECT * FROM Status

Templates:

SELECT * FROM Templates

Templates (filtered by category):

SELECT * FROM Templates WHERE Category = 'Invoices'

Templates (filtered by origin):

SELECT * FROM Templates WHERE Origin = 0

Templates (lookup by version):

SELECT * FROM Templates WHERE VersionId = 'your-version-id'

TemplateCategories:

SELECT * FROM TemplateCategories

TemplateTags:

SELECT * FROM TemplateTags

Connection Properties

The connection string properties are the various options that can be used to establish a connection. This section provides a complete list of the options you can configure in the connection string for this provider.

Property	Description
APIKey	The API Key (Bearer token) for your Carbone account.
AuthScheme	The scheme used for authentication. Accepted entries are APIKey or None. Allowed values are: BASIC, NONE, NTLM, OAUTH, APIKEY, OAUTH_CLIENT, OAUTH_PASSWORD
CarboneVersion	The major version of the Carbone API to target via the carbone-version request header. Allowed values are: 5, 4, 3, STAGING