API keys in PaperCut Hive and Pocket

Administrators use API keys to seamlessly integrate their PaperCut Hive or Pocket environment with their broader IT ecosystem. Rather than manually performing repetitive tasks or constantly checking the admin console, IT teams can use these authenticated endpoints to programmatically monitor, manage, and extract data from their print environment.

In PaperCut Hive and Pocket, API keys are:

• Generated directly within the PaperCut Hive or Pocket admin console.
• Secure, organization-specific credentials used to authenticate API requests via static Bearer token authentication.
• Used in standard HTTPS requests to authorize external systems to access your organization’s information via API calls — typically via Bearer tokens in the Authorization header, and in some cases via URL parameters (for example, the Health API).
• Strictly limited to specific API scopes so that external applications only have the minimum access required to function.

Available API key scopes

The current scopes are available using API keys in PaperCut Hive and Pocket:

• System Health Monitoring

More scopes coming soon.

Prerequisites

Before you begin integrating with PaperCut Hive or Pocket, ensure you have the following:

• Admin access: You must have administrative permissions for the PaperCut Hive or Pocket admin console.
• Organization ID: Your unique {orgId} (found in your browser URL when logged into the Admin Console).
• API Key: A valid key generated with the appropriate Scopes assigned.

Base API URLs

Use the Base URL that corresponds to your PaperCut data center (hosting) region. If you’re not sure which hosting region your organization uses, check out how to identify your data center region.

Authentication

Each request must include the API key in the Authorization header for every HTTPS request, using the following format:

Authorization: Bearer YOUR_API_KEY

For example, to call the system status endpoint using curl:

curl -X GET "https://api.cloud.papercut.com/health/v1/{orgId}/job-stats" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"

API keys are associated with a specific organization and can be revoked by an administrator at any time.

Security Best Practices

It is recommended to follow these security practices when using the API:

Connection security

• TLS 1.2 Requirement: PaperCut expects all API traffic to use TLS 1.2 or above. Requests using older cryptographic protocols will be rejected.

Authentication & authorization

• API key bearer tokens: Every request must include a valid API key as a Bearer token in the Authorization header:
  Authorization Bearer YOUR_API_KEY
• Restricted scopes: Each API key is scoped to specific API features (e.g., System Health Monitoring). Ensure your application only requests the minimum scope required for its function.

How to generate an API key

API keys are generated in the PaperCut Hive admin console.

1. Log in to the PaperCut Hive admin console as an administrator.

2. Go to General Settings and select the API Keys tab.

3. Select Generate.

4. In the Name field, enter a unique name for your key.

5. Optional: in Description, enter a description for your key.

6. Select Next. The Scopes step is displayed.

7. Review the Scopes assigned to your key, and use the checkboxes to select/unselect applicable scopes from the displayed list. (Additional Scopes will be added in the future)

8. Select Generate.

9. Copy and store the API key securely.

10. Select the checkbox to confirm that you have copied the API key.

11. Select Done. Your API key is generated.

Important notes:

• The API key is shown only once when generated.
• Administrators can revoke an API key at any time.
• Only one active API key can be used at a time. To create another API key, you must revoke the existing API key.

How to revoke an API key

1. Log in to the PaperCut Hive admin console as an administrator.
2. Go to General Settings and select the API Keys tab. The list of API keys is displayed.
3. Find the API key you wish to revoke, and in the same row select Revoke. A pop-up is displayed.
4. In the pop-up field, enter the word REVOKE in capital letters.
5. Select Revoke API key. The API key is revoked.

Error Handling

When an error occurs, the API returns an appropriate HTTP status code.

Common HTTP Status Codes