How to configure a Claims source

Authorize the request

MATTR VII supports two authorization methods. Choose based on how your data system already protects access, not on which is easier to set up. Reusing your existing access control is almost always the right call.

API key

Use api-key when your endpoint is protected by a static shared secret passed in a custom header. MATTR VII sends the configured value in an x-api-key header on every request.

{
    "name": "Customer records",
    "url": "https://records.example.com/claims",
    "authorization": {
        "type": "api-key",
        "value": "6hrFDATxrG9w14QY9wwnmVhLE0Wg6LIvwOwUaxz761m1J"
    },
    "requestParameters": {
        "customerId": {
            "mapFrom": "claims.sub"
        }
    }
}

When this is a good fit:

• You control the endpoint and can place it behind a key-checking gateway.
• The endpoint serves only the claims source use case, so a single shared secret is acceptable.
• You need a quick path to production without standing up an authorization server.

When to avoid it: if your organization already mandates OAuth for service-to-service traffic, do not introduce a parallel key-based path just for claims sources. Rotate the key periodically, and never reuse a key that protects other systems.

OAuth 2.0 client credentials

Use oauth-client-credentials when your endpoint is protected by an OAuth 2.0 authorization server (Auth0, Okta, Azure AD, Cognito, Keycloak, your own AS). MATTR VII performs the client credentials grant against your tokenEndpoint, then attaches the resulting bearer token as an Authorization: Bearer <token> header on every claims source request.

{
    "name": "Internal CRM",
    "url": "https://crm.example.com/api/claims",
    "authorization": {
        "type": "oauth-client-credentials",
        "tokenEndpoint": "https://auth.example.com/oauth/token",
        "clientId": "afd16fec-8131-4f0c-8f20-1cd5d67f8e29",
        "clientSecret": "1b41186347e4cc716155155cdecbded07536d0f5",
        "tokenEndpointAuthMethod": "client_secret_basic",
        "audience": "https://crm.example.com",
        "scope": "claims:read"
    },
    "requestMethod": "POST",
    "requestParameters": {
        "customerId": {
            "mapFrom": "claims.sub"
        }
    }
}

The tokenEndpointAuthMethod controls how MATTR VII presents the client credentials to your authorization server:

• client_secret_basic (default): credentials are sent in a Base64-encoded Authorization header on the token request. Use this with most off-the-shelf authorization servers; it is the OAuth 2.0 default.
• client_secret_post: credentials are sent in the token request body. Use this only when your authorization server does not accept basic auth on the token endpoint (some legacy or self-hosted servers).

Two optional fields tighten the issued token to the right resource:

• audience: set this when your authorization server scopes tokens by audience (Auth0, Azure AD). The value must match what the claims source endpoint expects in the aud claim.
• scope: set this when your endpoint requires a specific scope (for example claims:read). Omit it if your AS issues unscoped service tokens.

When this is a good fit:

• Your data system already lives behind your enterprise identity provider.
• You need centralized credential rotation, revocation, and audit.
• Different downstream systems (claims source, webhooks, internal APIs) should be authorized independently.

Map request parameters

requestParameters is the object MATTR VII sends to your endpoint. When requestMethod is GET (default), each top-level key becomes a query string parameter. When requestMethod is POST, the object is sent as a JSON request body. The keys you choose define the contract with your endpoint; pick names that match what your endpoint expects to receive.

Each parameter is configured in one of three shapes:

The rest of this step shows the data sources you can map from and the situations they fit.

Map from claims

The claims object holds every claim gathered during the issuance flow:

• In an Authorization Code flow, this is the union of claims returned by the Authentication provider and any claims added by an Interaction hook.
• In a Pre-authorized Code flow, this is the claims object you set when creating the Credential offer.

This is the most common source: it is how you pass a holder-specific lookup key (subject ID, email, employee number, license number) to your endpoint.

{
    "requestParameters": {
        "subjectId": {
            "mapFrom": "claims.sub"
        }
    }
}

{
    "requestParameters": {
        "employeeNumber": {
            "mapFrom": "claims.employee_number"
        }
    }
}

The path is dot-notation, so nested claims work the same way: claims.profile.country resolves to the country property of the profile claim.

Map from authenticationProvider

This object exposes metadata about the Authentication provider used in an Authorization Code flow:

• authenticationProvider.url: the configured provider URL.
• authenticationProvider.subjectId: the unique identifier of the authenticated user with the provider.
• authenticationProvider.providerId: the unique identifier of the provider configuration on your tenant.

Use it when your endpoint expects the canonical subject identifier rather than a claim returned in the ID token, or when the endpoint serves multiple tenants and needs the provider context to route the lookup.

{
    "requestParameters": {
        "subjectId": {
            "mapFrom": "authenticationProvider.subjectId"
        },
        "issuer": {
            "mapFrom": "authenticationProvider.url"
        }
    }
}

This source is not populated in Pre-authorized Code flows.

Map from credentialConfiguration

This object exposes the credential configuration being issued:

• credentialConfiguration.id: unique configuration identifier.
• credentialConfiguration.type: the credential type (for example org.iso.18013.5.1.mDL).
• credentialConfiguration.profile: the credential format (mobile for mDocs, compact for CWT, compact-semantic for semantic CWT).

This is useful when a single claims source backs several credential types and your endpoint needs to know which record set or schema to return.

{
    "requestParameters": {
        "holderId": {
            "mapFrom": "claims.sub"
        },
        "credentialType": {
            "mapFrom": "credentialConfiguration.type"
        }
    }
}

Your endpoint can then branch internally: returning driving privileges for an mDL request and academic transcripts for a study record request, against the same holder ID.

Map from wallet

The wallet object exposes information about the wallet making the credential request:

• wallet.id: the wallet's client identifier. Use it to apply per-wallet logic, for example returning a richer claim set to a wallet you have a direct partnership with.
• wallet.instanceId: the unique wallet instance identifier from the attestation JWT. Only populated when client attestation is enabled. Use it when your endpoint stores per-device state (renewal counter, device binding, instance-specific entitlements).

The same identifiers are exposed across both OID4VCI and Apple Wallet issuance flows, so a single wallet mapping works regardless of which protocol the wallet used to engage the issuer.

{
    "requestParameters": {
        "holderId": {
            "mapFrom": "claims.sub"
        },
        "walletId": {
            "mapFrom": "wallet.id"
        },
        "walletInstanceId": {
            "mapFrom": "wallet.instanceId"
        }
    }
}

Map from issuanceProtocol

issuanceProtocol is a top-level string that tells your endpoint which protocol the wallet engaged the issuer over. Currently the only supported value is openid4vci, covering both the Authorization Code and Pre-authorized Code flows. Contact us if you need support for additional issuance protocols.

Map this parameter when the same credential configuration is offered through multiple protocols and your endpoint needs to vary the returned data based on the channel, for example applying protocol-specific business rules.

{
    "requestParameters": {
        "holderId": {
            "mapFrom": "claims.sub"
        },
        "protocol": {
            "mapFrom": "issuanceProtocol"
        }
    }
}

Static parameters

A parameter with only a defaultValue is sent on every request, with no mapping. Use it for values that are constant for this claims source but that the endpoint still needs (API version, tenant code, fixed feature flag).

{
    "requestParameters": {
        "apiVersion": {
            "defaultValue": "2024-08"
        },
        "subjectId": {
            "mapFrom": "claims.sub"
        }
    }
}

A defaultValue can also be an object or an array, which is useful when the endpoint accepts structured filters in a POST body:

{
    "requestMethod": "POST",
    "requestParameters": {
        "filters": {
            "defaultValue": {
                "includeArchived": false,
                "regions": ["AU", "NZ"]
            }
        },
        "subjectId": {
            "mapFrom": "claims.sub"
        }
    }
}

Combine sources

You can mix mappings from different sources in a single configuration. The example below identifies the holder from the authentication provider, scopes the query to the credential type, tags the call with the wallet instance and protocol, and pins an API version:

{
    "requestMethod": "POST",
    "requestParameters": {
        "subjectId": {
            "mapFrom": "authenticationProvider.subjectId"
        },
        "credentialType": {
            "mapFrom": "credentialConfiguration.type"
        },
        "walletInstanceId": {
            "mapFrom": "wallet.instanceId"
        },
        "protocol": {
            "mapFrom": "issuanceProtocol"
        },
        "apiVersion": {
            "defaultValue": "2024-08"
        }
    }
}

Error-proof your queries with default values

Adding a defaultValue alongside mapFrom keeps issuance running when an expected claim is missing or evaluates to undefined. Without a fallback, the parameter is simply omitted from the request, which often causes the endpoint to return a 404 or an empty body, both of which can result in issuance failures depending on how your credential configuration is set up.

Two patterns are worth knowing.

Fallback to a safe value

When the mapped claim is optional, supply a defaultValue that your endpoint can interpret without error. Be careful that the fallback represents the right outcome: for a lookup key, the fallback should match a record your endpoint knows how to handle (often a "no match" placeholder), not a real user.

{
    "requestParameters": {
        "subjectId": {
            "mapFrom": "claims.sub"
        },
        "segment": {
            "mapFrom": "claims.customer_segment",
            "defaultValue": "standard"
        }
    }
}

Here, every holder gets a segment value. If the authentication provider did not return one, the endpoint receives standard and can apply its default rules.

Fallback to a structured value

defaultValue accepts strings, arrays, and objects, which is helpful when the endpoint expects a fixed shape:

{
    "requestMethod": "POST",
    "requestParameters": {
        "permissions": {
            "mapFrom": "claims.permissions",
            "defaultValue": []
        },
        "preferences": {
            "mapFrom": "claims.preferences",
            "defaultValue": {
                "locale": "en-US",
                "format": "standard"
            }
        }
    }
}

What a fallback cannot do

A defaultValue only fires when the mapping fails or resolves to undefined. It does not run when:

• The claims source returns an error (non-2XX status).
• The claims source returns an empty body or a body missing the claim you expected.
• The claims source times out (response longer than three seconds).

For those cases, the lever is in the Credential configuration itself: set a defaultValue on optional claim mappings so issuance can complete even if the claims source returns nothing useful. The two layers compose: the claims source defaultValue keeps the outbound request well-formed, and the credential configuration defaultValue keeps the outbound credential well-formed.