poai_ Server to server API key
- Rights of the account that creates it (admin: whole account)
- Never ship it in browser code
- No Origin header required
- Blocked for MCP
- Can be limited to IP addresses
Authentication and keys
One bearer token. Every endpoint.
Every product endpoint of the PaperOffice API expects the Authorization: Bearer header. No OAuth flow, no refresh.
Two token types, clear permissions, documented rate limits.
One header No OAuth flow Revocable at any time
- Own EU infrastructure Your data remains in Europe.
- ISO/IEC 27001 certified Certificate on request under NDA.
- SOC 2 Type II in preparation International audit standards.
- 24+ years of experience Proven. Stable. Future-proof.
curl -X POST "https://api.paperoffice.ai/latest/job/add/workflow" \ -H "Authorization: Bearer po_ut_YOUR_API_KEY" \ -F "file_1=@invoice.pdf" \ -F "idp_collection=invoice" \ -F "model=basic-pro-max"import requestsresponse = requests.post( "https://api.paperoffice.ai/latest/job/add/workflow", headers={"Authorization": "Bearer po_ut_YOUR_API_KEY"}, files={"file_1": open("invoice.pdf", "rb")}, data={"idp_collection": "invoice", "model": "basic-pro-max"},)print(response.json())const form = new FormData();form.append("file_1", new Blob([await readFile("invoice.pdf")]), "invoice.pdf");form.append("idp_collection", "invoice");form.append("model", "basic-pro-max");const response = await fetch("https://api.paperoffice.ai/latest/job/add/workflow", { method: "POST", headers: { Authorization: "Bearer po_ut_YOUR_API_KEY" }, body: form,});console.log(await response.json());First call
Set the header, pick the pipeline, send
The path after /latest/job/add/ is the operation name: usually in handler___command form (for example paperoffice_aiocr___generate), and for structured IDP the dedicated workflow pipeline.
- One header
Authorization: Bearer po_ut_… — that is all a product endpoint needs. poai_ and po_ut_ send no Origin header.
- Pipeline in the path
handler___command with three underscores; workflow is the exception with its own slug. Dot notation is answered with HTTP 400 JOB_CONFIG_INVALID.
- Result or job_id
client_wait defaults to true: the API holds the connection and returns the result inline. If the hold window is not enough, you get HTTP 202 with job_id and poll_url for GET /latest/job/get/{job_id}.
For idp_collection=invoice, basic-pro-max is the recommended model. The model actually used is returned in the response field model and can differ from the requested one.
Token types
Two token types, cleanly separated
Both belong on the server. You create, rotate and revoke them in the app under Account → API.
po_ut_ User-scoped User Token
- Carries its user's permissions
- Never ship it in browser code
- No Origin header required
- Accepted for MCP
Calls straight from the browser do not use these two tokens but the publishable key po_pk_ — origin-locked, budget- and rate-limited. See publishable keys
Permissions
What a user token may do
A user token has exactly its user's permissions in these areas. Individual areas cannot be granted when it is created; to narrow access, use a group token (po_gt_) with the permissions of a user group.
- Documents
documentsUpload, download, processing
- Workspaces
workspacesManage folders and structure
- AI Jobs
ai_jobsOCR, IDP, extraction
- Billing
billingRead usage and balance
- Users
usersManage team members
- Webhooks
webhooksReceive events
- Knowledge Base
knowledge_baseKnowledge base and FAQ
- Agents
agentsConfigure IDP agents
- Workflows
workflowsCreate automations
- Compliance
complianceAudit, GDPR, archiving
Rate limits
What the API counts
Counting happens per token; without a bearer, per IP address. The values below are the documented minimums that apply on every plan.
- 5
- requests per second
- 30
- requests per minute
- 100
- requests per hour
- 500
- requests per day
- Remaining budget is in the response header
The RateLimit-* and X-RateLimit-* headers on every response tell you what is left in the current window.
- Exceeded: HTTP 429
The API answers with RATE_LIMIT_EXCEEDED. Retry after the time given in the Retry-After header.
- Higher plans raise the values
Paid plans go beyond these minimums. Which plan covers what is on the pricing page.
Security
What secures a key
Six mechanisms that take effect in production — each with a verifiable status code or a place in the app.
- Rotation and revocation
Keys are created, listed, rotated and revoked in the app under Account → API. A revoked token answers with HTTP 401 TOKEN_NOT_FOUND.
- Expiry and validity
Expired tokens return HTTP 401 BEARERTOKEN_EXPIRED, malformed ones HTTP 401 INVALID_TOKEN. Publishable keys are valid for 180 days from creation.
- Limits per token
On the Free plan, rate limits apply per token. On paid plans they count per account, and as long as credits are available, no rate limits apply there.
- Origin lock in the browser
Publishable keys require an allowlisted Origin on every request; otherwise the API answers 403 ORIGIN_HEADER_REQUIRED or DOMAIN_NOT_ALLOWED.
- Trace the usage
Every billed response carries a _billing block; the per-call breakdown comes from GET /latest/billing/usage-detail.
- Hard blocks
Account login, key management, OAuth, partner admin, payment-method mutation and password-cracking are blocked for browser keys. Product APIs including billing reads and webhooks are allowed. Workspace delete, empty trash and legal-hold release only work in the app (403 UI_ONLY_ENDPOINT).
Related
What sits next to this
The pages that cover operations around authentication.
Get started
Create the key, set the header, send
You create the key in the app under Account → API. The first call is laid out step by step in the first API call guide.
Operations and trust
What enterprise teams check before the first call
Contracts, security, support and limits, all linked in one place.
- Security and compliance ISO/IEC 27001 certified, SOC 2 Type II in preparation, own EU infrastructure.
- SLA 99.9% Availability per calendar month, contractually assured.
- Data processing agreement (DPA) Data processing agreement under Art. 28 GDPR.
- No sub-processors One provider for engine, storage and processing.
- Technical support Direct line to the support team, with a ticket.
- Rate limits and headers Documented minimums per token, RateLimit headers in every response.
- Pricing and credits Transparent credit prices per call.
Next station
Where to go next
The recommended next step in the developer funnel and two fitting branches.
