Credential Requirements

The Utility Registry uses credentials of the Utility Credential to authorize role-based onboarding (Provider and Registrar) and token actions (minting/burning and transferring).

Requirements for these credentials are defined within the Service Configurations (for roles) and Instrument Configurations (for token actions).

1. Credential Requirements

A PartyCredentialRequirement acts as a gatekeeper for specific actions. It defines which party must issue a credential and which claims that credential must contain.

Configuration

Credential requirements are enforced at multiple levels:

  • Role-Based Onboarding:

    • Operator level: Defined in OperatorConfiguration to control which parties may onboard as Providers.

    • Provider level: Defined in ProviderConfiguration to control which parties may onboard as Registrars under that provider.

  • Token Actions:

    • Instrument level: Defined in InstrumentConfiguration to control token-related actions:

      • issuerRequirements: Required for requesting mints and burns.

      • holderRequirements: Required for sending and receiving tokens.

Note

Requirements may be left empty, in which case the corresponding actions are permitted without credential verification. For example, an empty holderRequirements allows any party to hold and transfer tokens.

Validation

All PartyCredentialRequirement configured for an action MUST be satisfied.

To validate that a party (the subject) is authorized to perform an action, it is verified that for each PartyCredentialRequirement configured for that action, there is a Credential meeting the following conditions:

  1. Issuer Match: The credential must be issued by the issuer specified in the requirement.

  2. Claim Verification: All required claims must be present in the credential, and the party being authorized (the subject) must be the subject of the corresponding Claim\s.

  3. Temporal Validity: The credential must be valid at the time of verification (i.e., its validity period has commenced and has not expired).

  4. Holder Match: The credential must be held by the subject party or the issuer.

Note

Atomic Requirements: If a PartyCredentialRequirement specifies multiple claims, all such claims must be satisfied by a single credential. However, if multiple PartyCredentialRequirement are configured for an action, a different credential may be used to satisfy each requirement.

Note

Credentials undergo validation during both the request and execution phases. As a result, if a credential is revoked or expires between these phases, the action will fail during execution.

2. Credential Types

Registry requirements MAY be satisfied using one of two credential types, distinguished by the party that holds the credential.

Credentials held by the Subject

In this model, the Subject of the credential is the Holder.

  • Usage: Proving external attributes, such as a license to operate as a financial institution. Issued, e.g., by trusted third parties (regulators, industry bodies).

  • Acquirement: Because the holder is a signatory, these credentials must be explicitly accepted by the party itself.

  • Disclosure: As the party is a signatory, they have visibility of their own credentials.

Credentials held by the Issuer

In this model, the Issuer of the credential is also the Holder. The Subject is not a signatory and not necessarily an observer of the credential.

  • Usage: Managing internal “allowlists” for specific instruments. Issued by, e.g., an instrument administrator.

  • Acquirement: Unilaterally created by the issuer of the credential.

  • Disclosure: As the party (or subject) is not necessarily an observer, these are typically disclosed by the registry’s off-ledger endpoints when required for specific actions.

Also see the page on :doc:../../how-tos/registry/allowlist/allowlist for an example of how to manage credentials for the purpose of allowlisting.

.. note:: A credential requirement does not specify the required credential type; either is valid. It is only verified that the holder of the credential is either the party performing the action (i.e., the subject) or the issuer of the credential.

Note

A credential requirement does not specify the required credential type; either is valid. It is only verified that the holder of the credential is either the party performing the action (i.e., the subject) or the issuer of the credential.

3. Examples

Onboarding as Registrar

The Provider, say Provider_Party_ID, could require in its ProviderConfiguration that to onboard as a Registrar (or instrument admin), a party must have a credential matching the requirement:

  • Issuer: Provider_Party_ID

  • RequiredClaims: [("hasRegistryRole", "Registrar")]

Result: For the onboarding of a party (User_Party_ID) to go through, this means their credential must satisfy:

  1. It is issued by Provider_Party_ID.

  2. It contains a claim with property “hasRegistryRole”, value “Registrar”, and subject User_Party_ID.

  3. The holder is either User_Party_ID or the Provider_Party_ID.

  4. The credential must have commenced and not be expired.

Transfer of an Instrument

In the InstrumentConfiguration of an instrument (“INST”), the Registrar (Instrument_Admin_Party_ID) may specify that parties involved in transfers must have a credential matching the requirement:

  • Issuer: Instrument_Admin_Party_ID

  • RequiredClaims: [("isHolderOf", "INST")]

Result: For a transfer to go through, both the sender (Sender_Party_ID) and the receiver (Receiver_Party_ID) must have a credential that matches the criteria. Specifically, for the sender, the credential must satisfy:

  1. It is issued by Instrument_Admin_Party_ID.

  2. It contains a claim with property “isHolderOf”, value “INST”, and subject Sender_Party_ID.

  3. The holder is either the Sender_Party_ID or the Instrument_Admin_Party_ID.

  4. The credential must have commenced and not be expired.