Claim sets
Issue several distinct credentials of the same credential configuration to a single user.
Claim set identifiers are offered as an open beta preview feature and are not generally available yet. They are available on all tenants, and their behavior may change in a way that breaks existing integrations before they become generally available.
Overview
By default, MATTR VII treats every credential a user holds from the same credential configuration as a copy of one credential. A wallet can store several of them, for example when the user claims on more than one device. But they all share one credential reference, so MATTR VII cannot give each one different data, or find, update or revoke one of them on its own.
Claim sets remove that limit. A claim set is one distinct credential's worth of claims, named by an identifier that you choose. In practice that identifier is usually a key you already hold: the record number you would use to look the record up in your own system. By supplying several claim set identifiers for the same credential configuration, you can issue the same user several credentials of that type, each carrying different data, and each managed independently in the holder's wallet.
Claim sets are unrelated to Claims sources, despite the similar name. A Claims source is where MATTR VII fetches claims from. A claim set is which of several credentials of the same type the claims belong to. The two work together: MATTR VII passes the claim set identifier to your Claims source so it can return the right data.
What this enables
- Held-on-behalf-of credentials: A parent can hold a separate birth certificate for each of their children, and each certificate is managed as a separate credential.
- Several records of the same type: A person can hold a registration for each vehicle they own, or a professional license for each field they are licensed in.
- Multiple qualifications of the same type: A learner can hold several micro-credentials that share a credential configuration but certify different subjects.
- A mix of your own and held-on-behalf-of credentials: A person can hold their own certificate alongside one they hold for another adult, both from the same credential configuration.
- Independent lifecycle management: Each credential is stored, updated and deleted on its own, without affecting the others.
Key terms
Claim sets involve a few identifiers. The examples on this page follow one family. Alex keeps three birth certificates in one wallet: their own, and one each for their children Sam and Riley.
Credential configuration
A credential configuration defines one type of credential, such as a birth certificate. Claim set identifiers are not part of the credential configuration. One birth certificate configuration can issue any number of certificates. Instead, when you create a credential offer, you list the claim set identifiers under the ID of the configuration they belong to, because a record number only has meaning within one type of credential. This also lets a single offer carry claim sets for more than one type of credential.
Claim set identifier
You choose this identifier. It is your own record number for each certificate, for example
BC-1001 for Alex, BC-1002 for Sam and BC-1003 for Riley. Pick a value that never
changes for the life of the record, because MATTR VII treats a new identifier as a new
credential. The wallet never sees it. It appears as claimSetId in API responses and in
requests to your Claims source.
Credential identifier
MATTR VII creates one credential identifier for each claim set, and gives it to the wallet in
the token response. The wallet uses it to ask for each certificate in turn. Treat it as an
opaque value. It never contains your record number. For mDocs, it is also returned on the
credential response as credential_bundle_id, so you can match an issued credential back to
your record.
Credential reference
A credential reference is "this user's certificate for this record", no matter which device
it is on. Alex has three, one for each record. A reference stays the same when a certificate
is reissued. Its identifier is credentialReferenceId.
Credential bundle
A credential bundle is one issued credential as it sits in one wallet. In this example, each
credential is one birth certificate, issued as an mDoc. Each claim set gets its own bundle, even
when several credentials are claimed from one offer into the same wallet. If Alex
claims all three certificates on a phone, the phone holds three bundles, one for each record.
If Alex also installs the wallet on a tablet, Sam's certificate has one credential reference and
two bundles. A bundle is what you target when you update a certificate that is already in a
wallet. Its identifier is credentialBundleId.
Use the credential reference to identify a certificate, for example to link it to your record. Use the credential bundle to act on one copy, for example to update it. See Relationship hierarchy for how references, bundles and the credentials inside them fit together.
Credential references and credential bundles are the same objects that Credential Update uses. You can issue credentials with claim sets without ever updating them, and you can update credentials that were not issued with claim sets.
A worked scenario
Suppose you are a government registry that issues birth certificates. Your system of record already holds a stable registration number for every certificate. A name correction changes the values inside a record, but not which record it is. That makes these numbers good claim set identifiers.
- Configure your Claims source once to accept the identifier, by mapping a request
parameter from
claimSetId. This is opt in. If you do not declare the mapping, your Claims source never receives the identifier. - Decide what Alex can hold. Your own entitlement check confirms that Alex can hold
BC-1001,BC-1002andBC-1003. You list these record numbers on a Pre-authorized Code offer, or return them from your Interaction hook. - MATTR VII hides your record numbers. The wallet receives one credential identifier per record instead, so your record numbers never reach the device.
- The wallet claims each certificate separately. For each credential identifier, MATTR VII looks up the matching record number, calls your Claims source with it, and issues a certificate that holds only that person's claims.
Alex ends up with three birth certificates side by side. Each one can be viewed, updated and deleted on its own. Without claim sets, MATTR VII would treat all three as copies of one birth certificate, with no way to tell Sam's apart from Riley's.
If Sam's certificate is later amended, you have two options:
- Issue a new copy: Create an offer that names only
BC-1002. Only that certificate is issued, and the other two are left untouched. - Replace the copy Alex already holds: Target Sam's existing credential bundle, so the wallet replaces the old certificate rather than storing a second one. See Credential Update.
How it works
- You supply claim set identifiers, either on a Pre-authorized Code flow offer or from an Interaction hook during an Authorization Code flow.
- MATTR VII scopes the authorization grant to those claim sets. Any access token issued from that grant is limited to the same set.
- The token response carries
authorization_details, listing onecredential_identifierper claim set for each credential configuration. - The wallet makes one credential request per
credential_identifier. - MATTR VII resolves the identifier to its claim set, passes
claimSetIdto your Claims source, and issues a credential containing only that claim set's data.
Supplying claim set identifiers
There are two entry points, one per flow. On a Pre-authorized Code offer, credentials names
which claim sets to issue, and claimSets supplies their claims. On an Interaction hook
during an Authorization Code flow, claimSets alone does both.
| Entry point | Where | Shape |
|---|---|---|
| Pre-authorized Code flow offer | credentials and claimSets on the offer request | credentials maps configuration IDs to claim set IDs. claimSets maps configuration ID, then claim set ID, to claims |
| Interaction hook | claimSets in the response JWT | Maps configuration ID, then claim set ID, to claims, same as the offer |
Claim values are optional in both places. Supply them directly in claimSets, set a claim
set's value to an empty object and let your Claims source resolve it at issuance time using
claimSetId, or do both. These are not alternatives: claims are resolved in order, with each
step overriding the last. Persisted user claims, then persisted claim set claims, then the
claims from your Authentication Provider and the sibling claims on the offer or hook, then
the values in claimSets, then your Claims source. See the
guide for worked examples of both.
On an Interaction hook, an empty object is how you name a claim set that carries no claims,
because MATTR VII takes the identifiers from the keys of claimSets. On a Pre-authorized Code
offer, credentials names them, so you can omit claimSets altogether.
Requirements
- Claim sets are an open beta preview feature and are available on all tenants. You do not need to request access.
- The Pre-authorized Code flow entry point supports mDocs credential configurations only.
Wallet compatibility
Claim sets need nothing new from the wallet as long as each credential configuration in an
offer carries a single claim set. Only offers that carry two or more claim sets for the same
credential configuration need a wallet that sends credential_identifier.
The wallet never sees or sends your claim set identifiers. MATTR VII records which claim sets
belong to each authorization grant, and resolves the claim set itself when the wallet asks for a
credential. A wallet that does not support credential identifiers asks by
credential_configuration_id instead, and the result depends on how many claim sets the grant
holds for that configuration:
| Claim sets for the configuration | Result for a wallet without credential identifier support |
|---|---|
| None | The credential is issued as it would be without claim sets. |
| One | MATTR VII uses that claim set and issues the credential. Your Claims source still receives the claimSetId, so the credential is the same as one claimed by a newer wallet. |
| Two or more | The request is rejected with invalid_credential_request, because MATTR VII cannot tell which claim set the wallet wants. The wallet does not receive that credential. Other credential configurations in the same offer are not affected. |
In the running example, an offer for Sam's certificate alone works with any wallet. An offer that carries Sam's and Riley's certificates together fails for a wallet without support, so Alex receives neither certificate.
The MATTR Holder SDKs send credential_identifier from iOS v6.2.0, Android v7.2.0, and React
Native v10.1.0. See OID4VCI feature support for
details. If your holders might use an older version or a third-party wallet that ignores
credential_identifiers in the token response, either issue one claim set per credential
configuration in each offer, or require holders to upgrade their wallet before you send offers
that carry several.
Limits and considerations
- Supplying claim set identifiers is optional. Where you do supply them, each credential configuration takes between 1 and 50 identifiers, so an empty list is rejected.
- Each claim set identifier is between 1 and 255 characters.
- Wallets must not send
authorization_detailson the token request. The credential issuer determines it, and a request that includes it is rejected withinvalid_authorization_details. - When a grant binds more than one claim set for a configuration, a credential request that
supplies only
credential_configuration_idis ambiguous and is rejected. The wallet must sendcredential_identifierinstead. - When a grant binds a single claim set,
credential_configuration_idon its own is still sufficient, so existing integrations keep working unchanged. See Wallet compatibility. credential_bundle_idis returned on mDocs credential responses only.
Next steps
How would you rate this page?
Last updated on