Credentials and card types | HIS User documentation

Credentials are records for access tokens that ICAP manages separately from people. The current API supports card credentials and PIN credentials. A credential becomes useful only after assignment to an identity or to a visitor in a visit.

Choose a credential

Type	Use it for	Important behavior
Card credential	A physical badge or card identifier	Requires a card type and may contain card ID, facility ID, or card code according to the card type's constraints.
PIN credential	A numeric access credential	Supply `value` as a string of ASCII digits, up to 16 characters. It is accepted only on creation and omitted from normal responses. PIN credentials select PACSs through their own `pacsMappings`.

Both credentials can carry external IDs and supported custom fields. They can be active or inactive and are managed with their own create, list, get, update, and remove endpoints.

Configure card types first

A card type is a tenant-scoped business definition such as “Employee badge” or “Visitor pass.” It provides:

The intended recipient: identity, visitor, or any.
A customer-friendly name and description.
Per-PACS card-format mappings, where required.
Format-derived constraints for card identification fields.

Create card types before creating card credentials. Configure mappings from the PACS card formats that ICAP discovers; do not guess device-specific formats. A card credential's cardType is an ICAP card-type ID, not a free-text label.

Assignment rules

Assign an identity credential through /identity/{identityId}/credential.
Assign a visitor credential through /visit/{visitId}/visitor/{visitorId}/credential.
A credential can have one active assignment only.
For a card-credential assignment, the card type must be eligible for the recipient: identity or any for an identity, and visitor or any for a visit participant. PIN credentials do not use card types. PIN assignments are also checked for overlapping PACS mappings with other PINs assigned to the same person.
To discover an existing assignment, use the credential's /assignment endpoint.

Remove the assignment before reusing a credential in a different active context. Removing an assignment is different from removing the credential record.

Change or replace a credential

Resource	Fields you cannot change after creation	How to make that change
Card credential	`cardType`, `cardId`, `facilityId`, `cardCode`	Create a replacement credential and change the assignment.
PIN credential	`value`	Create a replacement PIN credential and change the assignment.
Card type	`eligibleFor`	Create a card type with the required eligibility.

Use status to deactivate a retained credential. Removing its assignment does not remove the credential itself; removing the credential clears its active assignment.

Change or retire a card type

ICAP derives the card-identification constraints from the type's PACS format mappings. Clients cannot set the derived constraints directly. When formats impose different compatible bounds, the effective constraints use their stricter intersection. Incompatible constraints reject the mapping change.

While non-removed card credentials reference a card type, mapping changes cannot tighten its effective constraints. Deactivating a credential does not remove that dependency. Remove the referencing credential records before deleting the type. A card type is physically removed when deletion succeeds.

Within a tenant and eligibility category, a PACS/format combination cannot be reused by another card type. A PACS cannot be deregistered while a card type maps to it.

Keep the existing concurrency and PACS cross-links.

Status and change control

Use credential status to manage whether a retained credential is active. Update or remove card credentials, PIN credentials, and card types with their current If-Match version. See updates and concurrency.

PACS mappings and card eligibility affect downstream use. For connected environments, read PACS integration; for the resource schemas and routes, see the API contract.