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 certificate as it sits in one wallet. If Alex installs the wallet on
a phone and 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.
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.
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. credential_bundle_idis returned on mDocs credential responses only.
Next steps
How would you rate this page?
Last updated on