Accounts & Authentication
API Keys
Create and manage API keys for scripts and integrations.
API keys let scripts, integrations, and other systems authenticate with Pluraprint without signing in as a person. Use them to report on printers, jobs, queues, materials, and sites, provision users, or upload sliced files. The API reference documents every REST endpoint, its required access, and its request and response fields.
Creating an API key
- Open Admin in the sidebar, then choose API Keys.
- Select Create API Key.
- Give the key a descriptive name: for example, “User provisioning” or “Reporting dashboard”, so your team can recognize what it’s used for later.
- Choose Access using the profiles below. Each key gets only the capabilities in that profile; choose the smallest one that covers your integration.
- Choose an expiration: 30 days, 90 days, 1 year, or a future custom date.
- Select Create.
| Access profile | Capabilities | Use |
|---|---|---|
| Queue reporting | queue:read | Queue completion estimates |
| Read printers | printers:read | Printer status and loaded materials |
| Read jobs and history | jobs:read, queue:read | Jobs, queue contents, lifecycle events, history, and estimates |
| Read materials | materials:read | Material variants, types, brands, and colors |
| Read sites | sites:read | Site details |
| Fleet reporting | printers:read, jobs:read, queue:read, materials:read, sites:read | All fleet reporting endpoints |
| Slicer uploads | files:upload | Upload files through the OctoPrint-compatible interface |
| Read users | users:read | User directory |
| Create and update users | users:read, users:write | User provisioning and ID number assignment |
| Manage users and role assignments | users:read, users:write, roles:write | User provisioning and role changes |
Role changes embedded in user creation or updates, including bulk requests and an empty
roles array, require roles:write as well as users:write.
Reporting access covers the whole deployment. A siteId filter selects a location; it does
not restrict the key to that site. Job reporting exposes job names and owner IDs, so grant
it only to integrations allowed to read that information.
Slicer uploads belong to the person who created the key. That person must still have upload permission, and uploaded jobs go through the normal preparation and approval process. See Submitting a Print Job.
Managing existing keys
The API Keys page lists every key created for your organization, showing:
- Its name and capabilities
- When it expires
- When it was last used
You can search the list by name. To revoke a key, for example, if it’s no longer needed or may have been exposed: select Delete. Any system using that key will immediately lose access.
Good practices
- Create a separate key for each integration, rather than sharing one key everywhere. This makes it easy to revoke access to a single system without affecting others.
- Rotate keys before their required expiration date.
- Treat API keys like passwords: never commit them to source control or share them over unencrypted channels.
Creating, viewing, and deleting API keys requires the appropriate permissions: see Roles & Permissions.
Replacing legacy keys
Keys created before scoped API keys were introduced are disabled and labeled Legacy key — replace before use. Create a replacement with the minimum access, update the integration, then delete the old key. Existing hashes cannot be converted to the new format.
Send the key as Authorization: Bearer <key> or X-API-Key: <key> over HTTPS. Missing,
invalid, and expired keys return HTTP 401; insufficient capabilities return HTTP 403.
Authorized REST operations record the key’s public identity and issuing user in the audit trail.