PRINTOOLS API REFERENCE

Server-to-server integration

The shop is already in the key.

Use the PRINTOOLS API to read and act on a shop’s work with clear scopes, predictable envelopes, and a tenant identity derived at authentication time.

Start with tenant auth Download OpenAPI Postman collection
01 / START

A short path to a first request.

For a shop connecting its own software, create a tenant credential in Settings → API. Owners and Admins control credential management.

01Create a keyChoose a label, scopes and an optional expiry in Settings → API.
02Save it onceThe raw key is revealed once. Put it in your server-side secret store.
03Call /v1/meConfirm the shop and granted scopes before building a workflow.
04Use least privilegeStart with the scopes your job needs. Review and revoke keys when ownership changes.

New tenant credentials start read-only. Their default set excludes sensitive reads. Add write or sensitive scopes deliberately in Settings, where their consequences are shown and acknowledged.

02 / AUTH

Tenant credential: one key, one shop.

This is the normal path for a shop automating its own PRINTOOLS account. The key itself identifies the single shop it can access.

Send this

X-API-Key is sufficient.

Send the tenant key from your service with every API request. Do not add a client secret or user bearer token.

  • The tenant is derived from the credential record.
  • X-PrintTools-Organization-Id is optional.
  • If the optional org header is sent, it must equal the credential’s shop.
Lifecycle

Scope, expiry, revoke.

Keys are scoped, may have an expiry, and can be revoked in Settings. Revocation and narrowing take effect for subsequent API authentication.

  • The raw key cannot be retrieved after its reveal response.
  • Use a separate key for each integration or environment.
  • Keep keys out of browsers, mobile apps and source control.
First request · tenant credential 
curl --request GET 'https://api.printools.io/v1/me' \
  --header "X-API-Key: $PRINTOOLS_API_KEY"

Optional matching header: add X-PrintTools-Organization-Id: $PRINTOOLS_ORG_ID only when your integration has a reason to carry it. It never selects a different shop for a tenant key.

03 / PARTNER

Partner apps act with an application and a person.

A partner integration is for an application that works across shops. It must authenticate the application and the user who authorised the call.

Every data request needs all four

A complete partner request

  • X-API-Key — partner application ID
  • X-API-Secret — partner application secret
  • Authorization: Bearer <Cognito access token>
  • X-PrintTools-Organization-Id — required organisation selected during consent
OAuth 2.1

Authorization code + PKCE S256.

Partner connections use OAuth 2.1 authorization code flow with PKCE S256. The resulting call is limited by the credential’s scopes, the user’s consent, and that user’s current shop role.

Register redirect URIs with PRINTOOLS before starting an integration. Use the generated OpenAPI document for the exact HTTP contract.

Partner request · all required credentials 
curl --request GET 'https://api.printools.io/v1/me' \
  --header "X-API-Key: $PRINTOOLS_PARTNER_KEY" \
  --header "X-API-Secret: $PRINTOOLS_PARTNER_SECRET" \
  --header "Authorization: Bearer $PRINTOOLS_ACCESS_TOKEN" \
  --header "X-PrintTools-Organization-Id: $PRINTOOLS_ORG_ID"
04 / HTTP

Small, inspectable HTTP rules.

Every endpoint below is derived from the OpenAPI contract. Read the endpoint parameters and required scopes before sending a request.

2xx envelope

Successful requests return a consistent shape.

{
  "status": true,
  "message": "…",
  "data": { }
}
Non-2xx envelope

Failures are structured for code.

{
  "error": "INSUFFICIENT_SCOPE",
  "message": "…",
  "status": false
}
Rate limits

Read the live limits endpoint.

Use GET /v1/reference/limits for the current request, batch and page ceilings. On 429, wait for the whole-second Retry-After value before retrying.

Idempotency

Make writes retryable.

Send an Idempotency-Key on write requests when a retry could repeat an effect. Replays return the original result and identify themselves with Idempotency-Replayed: true.

Paging

Use the documented page controls.

List endpoints describe their accepted query parameters in the explorer. Treat endpoint-specific response metadata as the source of truth rather than assuming every collection uses the same cursor shape.

Downloads

Use a presigned URL promptly.

Document responses can contain a short-lived presigned download URL. Download the file while it is valid; do not persist or treat the URL as a permanent resource identifier.

05 / EVENTS

Webhooks are signed, replayable deliveries.

Read the live event catalogue at GET /v1/reference/events before subscribing. The endpoint explorer lists the webhook routes and required scopes.

Subscribe

Store the signing secret when it is revealed.

POST /v1/webhooks returns a signing secret once. Use an HTTPS public endpoint without credentials in its URL. Do not rely on redirects for delivery.

Deliveries

Verify raw bytes before parsing JSON.

Verify X-Printools-Signature against the exact raw body, use a constant-time comparison, and reject stale timestamps. Event delivery is at least once, so make your handler idempotent.

Signature input 
# X-Printools-Signature: t=<unix-seconds>,v1=<hex-hmac>
signed_payload = "<t>.<raw request body>"
expected = HMAC-SHA256(signing_secret, signed_payload)

Delivery behaviour: respond quickly, process asynchronously, and use delivery history or the retry endpoint when a failed event needs attention.

06 / SPEC

Browse the generated endpoint contract.

The explorer reads the same-folder OpenAPI file. It does not send requests to the production API or accept credentials.

Endpoint explorer

DOWNLOAD OPENAPI 3.1 ↗

Loading endpoint contract…

The generated API contract will appear here when openapi.json is available beside this page.