Authentication

The REST API authenticates with a workspace API key sent in the X-API-Key header. Keys look like:

pc_live_xxxxxxxxxxxxxxxxxxxx

Creating a key

1. Sign in at imaginepdf.com .
2. Open Settings → API Keys.
3. Create a key (workspace admins only). Optionally set an expiration date.
4. Copy the key immediately — it is shown only once. Only a hash is stored, so a lost key cannot be recovered; create a new one instead.

Using a key

Send it on every request:

curl https://api.imaginepdf.com/api/v1/designs \
  -H "X-API-Key: $IMAGINEPDF_API_KEY"

Verifying a key

Returns the workspace the key belongs to. It is the cheapest way to check a key and the natural “connection test” for an integration — use it instead of listing designs.

curl https://api.imaginepdf.com/api/v1/me \
  -H "X-API-Key: $IMAGINEPDF_API_KEY"

Response 200 OK

{
  "status": "success",
  "data": {
    "workspaceId": "ws_abc123",
    "workspaceName": "Acme Inc",
    "userEmail": "you@acme.com",
    "keyName": "Zapier"
  },
  "error": null
}

workspaceName is a good label to show users when they connect an ImaginePDF account, and keyName distinguishes two keys issued from the same workspace.

Scope

• Workspace-scoped. A key acts within exactly one workspace. Designs, assets, credits, and batch jobs all belong to that workspace.
• Plan-gated. API access itself is a plan feature (useApiKeys). If the workspace plan does not include it, key creation and all key routes return HTTP 403. See Credits & plans.

Authentication errors

See Errors for the complete table.