Authorization

Most API requests require authentication, or return only public data when authentication isn’t provided. You can use an OAuth 2.0 token to authenticate with the API by passing it in the Authorization header.

Example of using the OAuth 2.0 token in a header:

curl --header "Authorization: Bearer OAUTH-TOKEN" "https://..."

All OAuth access tokens are valid for one hour after they are created. You can use the refresh_token parameter to refresh tokens. See OAuth 2.0 token documentation for how to request a new access token using a refresh token.

The OAuth protocols uses Client ID to identify the client application. The Client ID is not confidential and can be safely exposed in client side code, it is usually a random string or UUID. It can be shown during the consent screen to show which application is requesting access to user data and thus helps users make informed decisions about granting permissions. Security comes from other mechanisms (client secrets, PKCE, redirect URI validation).

Client IDs can be used in combination with client secrets (for confidential clients). The Client ID is essentially the “username” that identifies your application to the OAuth provider, while the client secret (if used) acts as the “password.”.

Client IDs needs to registered beforehand. Until we provide a selfregistration functionality for ezeep organization administrators, we provide a simple web formular the interested customer can request their unique Client ID that will be created by our support team. Part of the client registration process are the allowed authorization flows along with redirect URIs, scopes, etc.

Supported OAuth 2.0 Authentication Flows

ezeep Blue supports the following authorization flows:

  • Authorization code: Secure and common flow. Recommended option for secure server-side apps (confidential, secret must not leave customers backend !). Can be used for SPAs or desktop apps with internet browser capabilities also also, ClientID should be marked as Public and no secret is defined in this case. This use case is classified as less secure because the tokens are returned directly to the clients without a backend component being able to check or intervene.
  • Resource owner password credentials: Direct username/password authentication, to be used only for securely hosted, first-party services. ezeep recommends against use of this flow. Treated as insecure.

The draft specification for OAuth 2.1 specifically omits both the Implicit grant and Resource Owner Password Credentials flows.

  • Pairing Code Grant/Device Authorization Flow Secure flow oriented toward devices or command line programs and scripts without direct browser access. Requires a secondary device or at least an internet bower to complete the authorization flow. Cannot be used with Social login or OIDC/SAML authenticated principals. No secret needed (and shall not be issued, since it does not provide any security as the name could imply), i.e. the client ID type is public
  • Authorization Code Flow with PKCE Extended version of the Authorization Code Flow with additional security for public clients:
    • Single-Page Applications (modern recommendation)
    • Mobile apps
    • Desktop applications
    • All public clients (e.g. scripts)
  • Client Credentials For server-to-server authentication without user interaction. At ezeep used for UMP customers only. The ClientID can only function with its corresponding fixed secret, which must remain completely secure.

All API uses JSON for data serialization unless otherwise specified.

Unique Client ID Assignment

Each client component and API customer requires a unique Client ID for proper identification.

Security and Access Control by Client IDs

Individual Authentication

  • Each client can be uniquely identified and authenticated
  • Prevents unauthorized access if one client is compromised
  • Enables proper authorization checks per client

Granular Access Management

  • Different clients can have and be restricted to different scopes and permissions
  • Allows fine-grained control over what each client can access
  • Supports principle of least privilege

Monitoring and Analytics

Usage Tracking

  • Monitor API usage patterns per client (customer or client application)
  • Identify which clients are using which endpoints

Audit Trails

  • Allows complete tracking of which client made which requests
  • Helps identify the source of issues or abuse

Operational Management

Client Lifecycle Management

  • Enable/disable specific clients without affecting others
  • Rotate credentials for individual clients
  • Manage client-specific configurations

Troubleshooting and Support

Issue Isolation

  • Quickly identify which client is experiencing problems
  • Provide targeted support and debugging
  • Isolate issues without affecting other clients

Without unique Client IDs, we lose visibility, control, and security over our API ecosystem.

Obtaining a ClientID for your Application

Be sure to keep the customer secret secure and never share it, especially in components that you will pass to others. If it is necessary to embed the client secret in the application, you may be using an incorrect authentication method.

To receive your Client ID and optional Client Secret, you will need to contact the ezeep Blue Integration Team via API Contact Form please also provide them with your redirect URI(s). The redirect URI(s) is where the user will be redirected to after they have granted permissions to your application. This is typically a URL on your server where you can handle the authorization code or access token. Only with this final redirection the code needed for getting the access_token and optionally a refresh_token will be provided.

Example applications and their Client ID settings

Customer Web Application (fixed/common URL for all users) that allows logged in users to print

Use Case: Corporate web portal where employees can upload and print documents through their browser. The secret is used on backend side only (handler of redirect_url)

Client ID Settings:

  • Flow: Authorization Code
  • Client Type: Confidential Client
  • Requires Client Secret: Yes
  • Redirect URI: https://printportal.company.com/oauth/callback
  • Scopes: printing

Document Management SaaS Integration (Multi-Organization)

Use Case: Integration with existing document management SaaS systems (like SharePoint Online, Google Workspace, Box, Dropbox Business) to add print functionality for different organizations. This scenario involves a SaaS provider serving multiple customer organizations, where each organization needs isolated access to their own ezeep environment.

Architecture Considerations

Multi-Tenant SaaS Provider Setup:

  • SaaS provider has one main application serving multiple customer organizations
  • Each customer organization has their own ezeep Blue environment (organiaz
  • Users from different organizations must only access their organization’s printers and print jobs
  • SaaS provider needs to handle OAuth flows for multiple ezeep instances

Client ID Strategy Options

Best for: SaaS providers with centralized authentication handling

Client ID Settings:

  • Flow: Authorization Code
  • Client Type: Confidential Client
  • Requires Client Secret: Yes
  • Redirect URI: https://dms-saas.com/ezeep/callback (single callback for all orgs)
  • Scopes: printing
  • Multi-Organization Handling: User login and user organization choice or via authorization server parameter

Option 2: Separate Client ID per Customer Organization

Best for: SaaS providers needing strict isolation or custom configurations per customer. Every ezeep organization admin has to register his unique Client ID and secret.

Client ID Settings:

  • Flow: Authorization Code
  • Client Type: Confidential Client
  • Requires Client Secret: Yes (every organization admin has to configure his own ClientID and secret in the admin portal of the SaaS Application)
  • Redirect URI: https://dms-saas.com/ezeep/callback/{org-id} (org-specific callbacks)
  • Scopes: printing

Security Considerations for Multi-Organization

Data Isolation:

  • Ensure tokens are stored with proper organization context
  • Validate organization membership before making API calls
  • Never mix tokens between organizations

State Parameter Usage:

  • Include organization ID in OAuth state parameter
  • Validate state parameter on callback to prevent CSRF
  • Use cryptographically secure random values

Configuration Management

Organization Onboarding Process:

  1. Customer organization signs up for DMS SaaS
  2. DMS SaaS admin configures ezeep integration
  3. Client ID registration with ezeep (if using separate Client IDs)
  4. Users within organization can authenticate and print

Advantages of Each Approach

Single Client ID Approach:

  • ✅ Simplified management and registration
  • ✅ Centralized authentication flow
  • ✅ Easier updates and maintenance
  • ✅ Single secret to manage
  • ❌ Less granular access control per organization

Multiple Client ID Approach:

  • ✅ Complete isolation between organizations
  • ✅ Organization-specific configurations
  • ✅ Individual access control and monitoring
  • ✅ Custom scopes per organization
  • ❌ More complex setup and management
  • ❌ Multiple secrets to secure

Command Line Tool or Script

Use Case: Command line utility or script that needs to authenticate without a browser interface.

Client ID Settings:

  • Flow: Pairing Code Grant (Device Flow)
  • Client Type: Public Client
  • Requires Client Secret: No
  • Redirect URI: Not required
  • Scopes: printing

Use Case: Headless (at least no browser) component that waits for and forward print data from ezeep Blue backend to print devices. One Client ID per connector implementation (multi-org use).

Client ID Settings:

  • Flow: Pairing Code Grant (Device Flow) - pairing code and Auth URL needs to be shown or printed out along with use instructions
  • Client Type: Public Client
  • Requires Client Secret: No
  • Redirect URI: Not required
  • Scopes: printing
  • Additional settings: Claim tp_id enabled, hardware serial number should be sent along auth request to get the same tp_id (and thus same printer configuration) after a device reset or missed refresh token.

Printer Integration or Release Station Device

Use Case: Client running on a printer or an assigned local backend service or headless (at least no browser) component that handles RFID/NFC/Hardware Token user authentication and allows to release waiting AnyPrinter print jobs. One Client ID per connector implementation (multi-org use).

Client ID Settings:

  • Flow: Pairing Code Grant (Device Flow) - pairing code and Auth URL needs to be shown or printed out along with use instructions
  • Client Type: Public Client
  • Requires Client Secret: No
  • Redirect URI: Not required
  • Scopes: printing
  • Additional settings: Claim tp_id enabled, hardware serial number should be sent along auth request to get the same tp_id (and thus same printer configuration) after a device reset or missed refresh token.

Mobile Application (iOS/Android) for printing

Use Case: Native mobile app that allows users to print photos, documents, and emails from their mobile device.

Client ID Settings:

  • Flow: Authorization Code with PKCE
  • Client Type: Public Client
  • Requires Client Secret: No
  • Redirect URI: com.company.printapp://oauth/callback (local redirect_url handler)
  • Scopes: printing

Single Page Application (SPA) - Browser-based printing interface

Use Case: JavaScript-based web application that runs entirely in the browser for document printing and management.

Client ID Settings:

  • Flow: Authorization Code with PKCE
  • Client Type: Public Client
  • Requires Client Secret: No
  • Redirect URI: https://printapp.company.com/callback
  • Scopes: printing

Desktop Application with browser integration

Use Case: Native desktop application (Windows/Mac/Linux) that integrates with system browsers for authentication.

Client ID Settings:

  • Flow: Authorization Code with PKCE
  • Client Type: Public Client
  • Requires Client Secret: No
  • Redirect URI: http://localhost:8080/oauth/callback (for development) or custom scheme
  • Scopes: printing, printing.printers.readonly

When to Activate Refresh Tokens

✅ ALWAYS Activate for These Scenarios:

Long-Running Applications

  • Web applications where users stay logged in for extended periods
  • Mobile apps that should maintain authentication across app launches
  • Desktop applications used throughout the workday
  • Background services that need persistent access

User Experience Requirements

  • Applications where re-authentication would be disruptive
  • Automated workflows that run without user intervention
  • Batch processing or scheduled print jobs
  • Apps where users expect to “stay logged in”

❌ Consider NOT Activating for These Scenarios:

Short-Lived Sessions

  • Single-use applications or one-time integrations
  • Temporary access scenarios (e.g., guest printing)
  • High-security environments requiring frequent re-authentication
  • Public/shared devices where persistent access is a security risk

Refresh Token Rotation Explained

Refresh token rotation is a security mechanism where the authorization server issues a new refresh token every time the old refresh token is used to obtain a new access token. This creates a “one-time use” pattern for refresh tokens.

How Refresh Token Rotation Works

Traditional Refresh Token Flow (No Rotation)

  1. Client gets: access_token + refresh_token
  2. Access token expires after 1 hour
  3. Client uses refresh_token → gets new access_token (same refresh_token)
  4. Client uses same refresh_token again → gets new access_token
  5. ♻️ Same refresh_token can be reused indefinitely

Refresh Token Rotation Flow

  1. Client gets: access_token + refresh_token_A
  2. Access token expires after 1 hour
  3. Client uses refresh_token_A → gets new access_token + refresh_token_B
  4. ⚠️ refresh_token_A is now INVALID
  5. Client must use refresh_token_B → gets new access_token + refresh_token_C
  6. ⚠️ refresh_token_B is now INVALID
  7. 🔄 Process continues with each refresh

Security Benefits

Reduces Attack Window

  • Stolen refresh tokens become useless after first use
  • Compromised tokens can’t be reused indefinitely
  • Replay attacks are prevented

Pros and Cons

✅ Advantages of Refresh Token Rotation

  • Enhanced Security: Stolen tokens become useless quickly
  • Breach Detection: Can detect when tokens are compromised
  • Automatic Cleanup: Old tokens are automatically invalidated
  • Compliance: Meets security standards for sensitive applications

❌ Potential Challenges

  • Implementation Complexity: Must handle token updates correctly
  • Client Synchronization: All client instances must use latest token
  • Network Reliability: Failed requests can invalidate tokens
  • Debugging Difficulty: Token issues are harder to troubleshoot