Authentication and authorization

ICAP uses bearer authentication. Obtain an ID token from HID Authentication Service, then include it in every ICAP API request:

Authorization: Bearer <id_token>

Prerequisites

Before calling ICAP, obtain the following values from your HID HIS administrator:

• ICAP API base URL, for example https://<your-icap-host>/icap/v1

• ICAP tenant ID

• HID Authentication Service base URL, ending in /authn

• Registered client ID and client secret

• Integration user name and password, if your approved flow uses password authentication

• ICAP role assignments for that user in the target tenant

The registered client must be permitted to use the authentication flow selected for the integration. This section shows the password grant because it is appropriate for a server-side integration with a managed integration user. If your organization mandates a different grant type, MFA, certificate authentication, or additional scopes, follow the values and process provided by your HID HIS administrator.

Obtain an ID token

The HID token endpoint is the configured Authentication Service URL followed by /token. Authenticate the registered client with HTTP Basic authentication and submit the integration user's credentials as form fields.

set +x # Prevent accidental printing of secrets by shells using xtrace.

AUTH_URL='https://<your-auth-host>/idp/<auth-tenant>/authn'
CLIENT_ID='<client-id>'
CLIENT_SECRET='<client-secret>'
USER='<integration-username>'
PASSWORD='<integration-user-password>'

TOKEN="$(
  curl --fail-with-body --silent --show-error \
    --request POST "${AUTH_URL}/token" \
    --user "${CLIENT_ID}:${CLIENT_SECRET}" \
    --data-urlencode 'grant_type=password' \
    --data-urlencode 'scope=openid' \
    --data-urlencode "username=${USER}" \
    --data-urlencode "password=${PASSWORD}" \
  | jq --exit-status --raw-output '.id_token'
)"

Tenant context and authorization

Every ICAP resource request includes the tenant ID:

https://<your-icap-host>/icap/v1/tenant/<tenantId>/identity

Authentication identifies the caller. The tenant path selects the data and authorization context. A valid token is not automatically authorized to access every tenant.

For each request, ICAP identifies the caller from the token, finds that caller's role assignments in the tenant named in the path, combines the permissions from those roles, and evaluates the permission required by the endpoint. ICAP does not create or manage user accounts; use HID Authentication Service for HID identity lifecycle and ICAP roles and permissions for tenant-scoped ICAP access.

Verify access before creating data

Use the permission catalog as a read-only connectivity check after obtaining a token:

BASE_URL='https://<your-icap-host>/icap/v1/tenant/<tenantId>'

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${TOKEN}" \
  "${BASE_URL}/permission"

A successful response confirms the token, ICAP host, and tenant path are usable. It does not confirm that the caller can perform every write operation.