External card integration (Preview)

Preview ModeThe External card integration feature is in "Preview Mode" only. You can request access to this feature by emailing HP.

HP Insights supports integration with third-party card systems. When External card integration is configured, printers retrieve and validate card details directly from your organization's identity provider rather than from HP Insights, performing real-time queries whenever card information is needed. This feature is available from HP Insights 4.1.

Before you begin

  • Build and deploy an identity assertion endpoint — it must be reachable before you can configure the settings on this page. See Build an identity assertion endpoint for what to set up first, and the External Card Provider API reference for the full contract.
  • Review how External card integration works — key behaviors, limitations, and authentication methods.

Configure External card integration

1

Navigate to Analysis > API in the web console.

2

In the External card integration section, enter the required settings. Refer to the Settings Reference below.

3

Toggle Allow card authentication via external API to ON.

4

Use the Test API Configuration section to verify the integration.

NoteAn Endpoint URL must be provided before the toggle can be activated.

Settings Reference

General Settings

Setting Description
Allow card authentication via external API

This allows card authentication through an external API. To enable it, toggle the switch ON.

An Endpoint URL must be provided before activation. Without a valid Endpoint URL, the feature cannot be enabled.
Endpoint URL

Add the API endpoint URL for the third-party card system. HP Insights will use this address to send requests to check user badges or cards using the customer’s own authentication system.

HTTP Signature Validation

Setting Description
Certificate URL

This certificate is used to establish secure communication between HP Insights and the third-party card system, ensuring the data exchanged is signed or encrypted for security.

This value is specific to your environment and is provided by HP. Do not modify this value.

OAuth bearer token authentication (Optional)

These settings are required when the Endpoint URL requires bearer token authentication.

Setting Description
Client Id A public identifier that uniquely identifies HP Insights to your OAuth authorization server. Think of it as a "username" for the application. It's issued by your identity provider (e.g. Azure AD, Okta) when you register HP Insights as a client application.
Client Secret The confidential password paired with the Client ID. It proves to your OAuth server that the token request is genuinely coming from HP Insights and not an imposter. It's issued alongside the Client ID when HP Insights is registered with your identity provider, and must be kept secure.
Client Scopes A space-separated list of permissions HP Insights is requesting when it asks for a token. Scopes tell the OAuth server what the token should be allowed to do (e.g. read user data, call a specific API). Your identity provider defines the valid scopes for your environment. This field can be left empty if your OAuth server doesn't require specific scopes, but the field itself must exist (it can't be null).
Token Endpoint The direct URL of your OAuth token endpoint (for example: https://example.com/tokens).
NoteStarting with HP Insights 4.4, using OAuth bearer tokens for authentication is supported. This means HP Insights can now fetch a secure token from your organization's OAuth server and use it to authenticate requests.

Testing API Configuration

Before rolling out to users, validate the integration end-to-end:

In the Test API Configuration section, enter a card number that exists in the third-party system. Click the Test button.

  • If the card ID exists, the integration will respond successfully.

  • If the card ID does not exist, the system will return the following error message:

The external service reported an error: card_not_found

Cause: HP Insights cannot connect to the external card authentication endpoint. This can occur if the endpoint URL is incorrect, network connectivity is blocked, or the endpoint's TLS certificate is invalid or expired.

Resolution:

  1. Verify that the Endpoint URL is correct in the External card integration settings.

  2. Use the Test Connection tool in the Web Console or test from an external network to verify the service is online.

  3. Check firewall and network rules to ensure HP Insights can connect to the endpoint.

  4. Verify that the endpoint's TLS certificate is valid and has not expired.

  5. Check backend server logs for incoming requests and look for authentication (401/403) or server/timeout errors (500/504).

Cause: The email address returned by the external identity system does not match a user account in HP Insights. Because HP Insights cannot identify the user, authentication fails.

Resolution: Ensure that the email address returned by the external identity system exactly matches the user's email address in HP Insights. If your organization uses SCIM provisioning, verify that user synchronization is working correctly. Otherwise, manually update the user records so that the email addresses match in both systems.

Related topics