Authentication

The Poli Page PHP SDK authenticates every request with a bearer token. A key belongs to exactly one environment of your organization, and every render uses the project’s copy published in that environment.

API keys

API keys and environments

An API key looks like pp_{env}_…, and the environment name in the key decides where the render goes. pp_sandbox_… renders in the sandbox: documents carry a watermark, do not count toward your quota, and expire 30 days after creation. pp_live_… and the keys of environments you create on a Pro plan (pp_{name}_…) render without a watermark and count toward your quota. Every key targets the same API host.

A key is pp_{env}_{32 lowercase hex}, where {env} is the name of the key’s environment. It matches this regex:

^pp_(?=[a-z][a-z0-9-]{0,19}_)[a-z][a-z0-9]*(?:-[a-z0-9]+)*_[0-9a-f]{32}$

| Environment | Key | Watermark | Counted | | ------------------------------------- | -------------- | --------- | ------- | | sandbox (every org) | pp_sandbox_… | yes | no | | live (every org, deletable on Pro+) | pp_live_… | no | yes | | created on Pro+ (e.g. staging) | pp_staging_… | no | yes |

“Counted” means the render counts toward the organization’s monthly PDF quota. sandbox documents expire 30 days after creation. There is no watermark option: a template that wants a watermark outside sandbox uses the poli-watermark class.

The SDK passes the key through as-is and does not check its format; the API rejects an unknown key with 401 INVALID_API_KEY. The one client-side check is that the key is a valid HTTP header value: a key with CR, LF, NUL or another control character other than tab (often a trailing newline from a .env value or a secret file) fails before any request is built with a PoliPageException (invalid_options) whose message never contains the key.

Pass the key to the client factory:

$client = PoliPage::client($_ENV['POLI_PAGE_API_KEY']);

The SDK never reads $_ENV['POLI_PAGE_API_KEY'] implicitly. You always pass the key in.

Custom base URL

The SDK targets https://api.poli.page by default. To go through a proxy or gateway, use the full constructor and pass baseUrl:

$client = new PoliPage(
    apiKey: $_ENV['POLI_PAGE_API_KEY'],
    baseUrl: 'https://pdf-gateway.internal.example', // your gateway's URL
);

Example

<?php

require __DIR__ . '/vendor/autoload.php';

use PoliPage\PoliPage;

$client = new PoliPage(
    apiKey: $_ENV['POLI_PAGE_API_KEY'],
    baseUrl: $_ENV['POLI_PAGE_BASE_URL'] ?? 'https://api.poli.page',
);

See also

• Configuration
• Errors