API Reference
Create Credential Offer
Returns an OID4VCI credential offer URI. See https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#section-10.1
This offer can be used more than once, and can be shared with multiple users. Each user will authenticate independently during the credential issuance workflow, allowing the same offer URI to issue credentials with different user-specific data to multiple holders.
Roles
Analytics Events
bearerAuthAuthorizationBearer <token>application/json- body
credentials*array<string>This array includes a list of identifiers for credential configurations that will be included in the credential offer. These identifiers are the id elements returned in the response when you create a credential configuration. To issue multiple credential formats of the same credential in a single flow, include all the required credential configuration id elements in the request payload.
request_parameters?Specifies a list of additional request parameters that the wallet can include in the authentication request.
Credential offer URI created
application/json- response
uri*stringGenerated URI that can be sent to a user's digital wallet via a message, a QR code or a deep link. When a multi-format credential offer is created, the generated URI offer is used to issue all the credential formats in a single workflow. The credential offer payload carries the offered credential configuration identifiers in both credential_configuration_ids and the deprecated credentials element. Wallet clients should read credential_configuration_ids, as credentials is retained for backward compatibility only and will be removed. Refer to the OID4VCI v1.0 alignment changelog entry.
curl -X POST "https://example.com/v1/openid/offers" \ -H "Content-Type: application/json" \ -d '{ "credentials": [ "707e920a-f342-443b-ae24-6946b7b5033e" ] }'{ "uri": "openid-credential-offer://?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Fmyissuer.example.com%22%2C%22credentials%22%3A%5B%22707e920a-f342-443b-ae24-6946b7b5033e%22%5D%2C%22credential_configuration_ids%22%3A%5B%22707e920a-f342-443b-ae24-6946b7b5033e%22%5D%2C%22request_parameters%22%3A%7B%22login_hint%22%3A%22user%40example.com%22%2C%22prompt%22%3A%22login%22%7D%7D"}Request authorization for access to resources
This endpoint is used to request authorization from the user for access to the requested resources. After the user approves the request, an authorization code is returned to the client. See https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-authorization-endpoint See https://www.rfc-editor.org/rfc/rfc6749.html#section-3.1
Analytics Events
response_type*"code"The response type, which must be 'code'.
"code"client_id*stringThe client identifier.
redirect_uri*stringThe URI to which the authorization server will redirect the user-agent with the authorization code.
scope*stringThe scope of the access request.
state?stringAn opaque value used by the client to maintain state between the request and callback.
code_challenge_method*"S256"The method used to derive the code_challenge, which must be 'S256'.
"S256"code_challenge*stringA high entropy random challenge generated by the client.
Redirection to client application with authorization code
curl -X GET "https://example.com/v1/oauth/authorize?response_type=code&client_id=string&redirect_uri=string&scope=string&code_challenge_method=S256&code_challenge=string"Exchange authorization code for access token
This endpoint is used to exchange an authorization code or a pre-authorized code for an access token, which is later used to request a credential.
- In an Authorization Code flow the authorization code is obtained from the authorization endpoint after the user has successfully authenticated.
- In a Pre-authorized Code flow the pre-authorized code is obtained from the offer URI.
See https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-token-endpoint for more information.
When the session binds claim sets, authorization_details is determined by the credential issuer. A request that includes authorization_details is rejected with invalid_authorization_details.
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.
Analytics Events
DPoP?stringDPoP proof JWT. A signed JWT that demonstrates proof-of-possession of a private key.
When to use:
- Token endpoint: Required when
dpop_jktwas provided in the authorization request - Credential endpoint: Required when using DPoP-bound access tokens (Authorization header must use format:
Authorization: DPoP <access_token>)
The DPoP proof must be a signed JWT with the following structure:
Header:
alg: Must beES256typ: Must bedpop+jwtjwk: Public key (JWK format)
Payload:
htu: HTTP URI of the target endpointhtm: HTTP method (e.g.,POST)jti: Unique identifier for this DPoP proofiat: Unix timestamp when the DPoP proof was createdath: Optional base64url-encoded SHA-256 hash of theaccess_token. Required when authenticating with the resource server.htcd: Optional base64-encoded SHA-256 hash (content digest) of the HTTP request payload used to validate integrity.
Each DPoP proof must be unique and cannot be reused across requests.
OAuth-Client-Attestation-PoP?stringOAuth-Client-Attestation-PoP proof JWT that demonstrates:
- Proof-of-possession of a private key from a wallet instance
- Binding to OAuth-Client-Attestation JWT
When to use:
- Token endpoint: When OAuth Client has client attestation enabled with
dpopRequiredset to false.
The OAuth-Client-Attestation-PoP proof MUST be signed with a wallet instance's private key that corresponds to the cnf.jwk claim from the provided
OAuth-Client-Attestation and must use the following structure:
Header:
alg: Must beES256typ: Must beoauth-client-attestation-pop+jwt
Payload:
aud: HTTP Host of the target endpointjti: Unique identifier for this OAuth-Client-Attestation-PoP proofiat: Unix timestamp when the OAuth-Client-Attestation-PoP proof was created
Each OAuth-Client-Attestation-PoP proof must be unique and cannot be reused across requests.
OAuth-Client-Attestation?stringJWT generated by the Client Attester (Backend) attesting to a validated Client Instance and bound to a key managed by the Client Instance, ensuring proof of possession.
When to use:
- When client attestation is configured for this client_id
Header:
alg: Must beES256typ: Must beoauth-client-attestation+jwtx5c: Must be an array of base64 encoded X509 End-Entity certificates bound to the configured client attestation root certificate.
Payload:
sub: OAuth client_id matching the requestclient_instance_id: Optional identifier to represent the client/app instance.iat: Unix timestamp when the token was createdexp: Unix timestamp when the token will expirecnf.jwk: JWK public key from the client instance that the authorization server uses to verify the signature of subsequent DPoP or PoP proofs.
application/x-www-form-urlencoded- body
client_id*stringThe client identifier.
grant_type*"authorization_code"The grant type, which must be 'authorization_code'.
"authorization_code"redirect_uri*stringThe redirect URI that was used in the authorization request.
code*stringThe authorization code obtained from the authorization endpoint.
code_verifier*stringSHA256 hash of the code_challenge in the authorization request.
Access token successfully returned.
application/json- response
access_token*stringThe access token issued by the authorization server.
token_type*"Bearer"The type of the token, which is always 'Bearer'.
"Bearer"expires_in*integerThe number of seconds until the token expires.
scope*stringThe scope of the access token.
authorization_details?array<>The credentials this token can be used to retrieve, one entry per credential configuration. Only returned when the session binds claim sets.
Each credential_identifiers value represents the credential for a single claim set, and is provided as credential_identifier when requesting a credential.
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.
curl -X POST "https://example.com/v1/oauth/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d 'client_id=string&grant_type=authorization_code&redirect_uri=string&code=string&code_verifier=string'{ "access_token": "KrrFP8GUeddJJtj7EF-4ugdvCl-dDdWwOqvAbvYsmfy", "token_type": "Bearer", "expires_in": 900, "scope": "mso_mdoc:org.iso.18013.5.1.mDL", "authorization_details": [ { "type": "openid_credential", "credential_configuration_id": "707e920a-f342-443b-ae24-6946b7b5033e", "credential_identifiers": [ "c3d4e5f6-a7b8-9012-cdef-123456789012", "d4e5f6a7-b8c9-0123-def1-234567890123" ] } ]}Issue a verifiable credential
Issues a credential to a holder upon presentation of a valid access token, as per OID4VCI. Supports encrypted and non-encrypted credential issuance.
For non-encrypted credential issuance the valid access token must be provided in one of the following header formats:
Bearer
- Authorization:
Bearer <access_token>. - Content-Type:
application/json - Body:
<credential request payload>
OR
DPoP Only required when using DPoP-bound access tokens.
- Authorization:
DPoP <access_token>. - DPoP:
<dpop_token> - Content-Type:
application/json - Body:
<credential request payload>
For encrypted credential issuance, contact us to configure how your MATTR VII enforces request and/or response encryption, and then:
- For request encryption,
Content-Typemust be set toapplication/jwtand the payload must be JWE formatted. - For response encryption, include the
credential_response_encryptionproperty in the raw request payload to specify encryption details.
Analytics Events
AuthorizationBearer <token>OID4VCI access token presented by a holder's wallet. Use the format: Authorization: Bearer <access_token>.
The wallet obtains this token from your tenant's token endpoint during a credential issuance flow. This is not the tenant management token used by operations that require bearerAuth.
DPoP?stringDPoP proof JWT. A signed JWT that demonstrates proof-of-possession of a private key.
When to use:
- Token endpoint: Required when
dpop_jktwas provided in the authorization request - Credential endpoint: Required when using DPoP-bound access tokens (Authorization header must use format:
Authorization: DPoP <access_token>)
The DPoP proof must be a signed JWT with the following structure:
Header:
alg: Must beES256typ: Must bedpop+jwtjwk: Public key (JWK format)
Payload:
htu: HTTP URI of the target endpointhtm: HTTP method (e.g.,POST)jti: Unique identifier for this DPoP proofiat: Unix timestamp when the DPoP proof was createdath: Optional base64url-encoded SHA-256 hash of theaccess_token. Required when authenticating with the resource server.htcd: Optional base64-encoded SHA-256 hash (content digest) of the HTTP request payload used to validate integrity.
Each DPoP proof must be unique and cannot be reused across requests.
- body
Exactly one of credential_configuration_id or credential_identifier is required.
credential_configuration_id*stringcredential_identifier?Credential IdentifierOne of the credential_identifiers values returned in the token response authorization_details, selecting the credential to issue for a single claim set.
Treat this value as opaque. It is derived by MATTR VII and does not encode the claim set identifier you supplied.
This property is mutually exclusive with credential_configuration_id, and only resolves while it remains bound to the grant. For mDocs, the same value is returned as credential_bundle_id on the credential response, so you can correlate an issued credential back to the claim set it was requested for.
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.
proofs?JSON object containing proof of possession of the key material the issued Credential shall be bound to.
credential_response_encryption?JSON object containing details for encrypting the issued credential in the response.
Credential issued
- response
credentials*array<>curl -X POST "https://example.com/v1/openid/credential" \ -H "Content-Type: application/json" \ -d '{ "credential_configuration_id": "2cdb2c15-39a7-4556-abab-4515ce2d831b", "proofs": { "jwt": [ "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..." ] } }'{ "credentials": [ { "credential": { "@context": [ "https://www.w3.org/2018/credentials/v1" ], "id": "http://example.edu/credentials/3732", "type": [ "VerifiableCredential", "AlumniCredential" ], "issuer": "https://example.edu/issuers/14", "issuanceDate": "2020-03-10T04:24:12.164Z", "credentialSubject": { "id": "did:example:123", "alumniOf": "Example University" }, "proof": { "type": "RsaSignature2018", "created": "2020-03-10T04:24:12Z", "proofPurpose": "assertionMethod", "verificationMethod": "https://example.edu/issuers/keys/1", "jws": "EXAMPLE_JWS_TOKEN_eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9aH0..." } } } ]}Retrieve issuer metadata
Returns OID4VCI issuer metadata. This is the standard OID4VCI Well Known endpoint for your tenant.
This endpoint is unprotected, public facing and can be deterministically found at the root of the tenant subdomain or alias by any party wishing to discover the OID4VCI capabilities.
OID4VCI credential issuer metadata retrieved
application/json- response
issuer?stringuriauthorization_endpoint?stringurijwks_uri?stringuritoken_endpoint?stringuriscopes_supported?array<string>response_types_supported?array<string>response_modes_supported?array<string>grant_types_supported?array<string>code_challenge_methods_supported?array<string>credential_issuer?stringuricredential_endpoint?stringuricredentials_supported?array<|||>DeprecatedThis field is deprecated and maintained only for backward compatibility.
Use credential_configurations_supported instead to discover supported credentials.
Refer to the OID4VCI v1.0 alignment changelog entry.
credential_configurations_supported?Supported credential configurations.
mdoc_iacas_uri?stringuricredential_response_encryption?Declares the issuer's ability to encrypt credential responses. When configured, MATTR VII can encrypt credential responses to specific wallet instances using encryption keys provided by the wallet application. This provides end-to-end encryption ensuring that credential data remains confidential and unreadable to intermediary backend servers.
credential_request_encryption?Declares the issuer's ability to receive and decrypt credential requests. When configured, wallet applications can encrypt credential requests to ensure sensitive information in the request is protected in transit. MATTR VII will decrypt the request as part of the issuance flow and enforce the configured encryption policies.
curl --request GET \ --url https://{tenantName}.{region}.mattr.global/.well-known/openid-credential-issuer \ --header 'Accept: application/json'{ "issuer": "http://example.com", "authorization_endpoint": "http://example.com", "jwks_uri": "http://example.com", "token_endpoint": "http://example.com", "scopes_supported": [ "ldp_vc:ExampleCredential" ], "response_types_supported": [ "code" ], "response_modes_supported": [ "query" ], "grant_types_supported": [ "authorization_code" ], "code_challenge_methods_supported": [ "S256" ], "credential_issuer": "http://example.com", "credential_endpoint": "http://example.com", "credentials_supported": [ { "format": "ldp_vc", "id": "string", "scope": "string", "@context": [ "string" ], "type": [ "string" ], "credentialSubject": {}, "cryptographic_binding_methods_supported": [ "did:key", "mso" ], "cryptographic_suites_supported": [ "Ed25519Signature2018", "ES256" ] } ], "credential_configurations_supported": { "2cdb2c15-39a7-4556-abab-4515ce2d831b": { "format": "ldp_vc", "id": "2cdb2c15-39a7-4556-abab-4515ce2d831b", "scope": "ldp_vc:TestCredential", "credential_definition": { "@context": [ "https://www.w3.org/2018/credentials/v1", "https://schema.org" ], "type": [ "VerifiableCredential", "TestCredential" ] }, "credential_signing_alg_values_supported": [ "Ed25519Signature2018", "BbsSignatureProof2022" ], "cryptographic_binding_methods_supported": [ "did:key" ], "proof_types_supported": { "jwt": { "proof_signing_alg_values_supported": [ "EdDSA" ] } }, "credential_metadata": { "display": [ { "name": "Test Credential", "logo": { "uri": "https://example.com/logo.png", "alt_text": "Example Logo" }, "locale": "en-US", "background_color": "#FFFFFF", "text_color": "#000000" } ], "claims": [ { "path": [ "credentialSubject", "firstName" ], "mandatory": true, "display": [ { "name": "First Name", "locale": "en-US" } ] } ] } }, "3dfe1c4a-5b6c-4e2f-9f3a-2b1c4d5e6f7g": { "format": "cwt_vc", "id": "3dfe1c4a-5b6c-4e2f-9f3a-2b1c4d5e6f7g", "scope": "cwt_vc:TestCredential", "types": [ "VerifiableCredential", "TestCredential" ], "cryptographic_binding_methods_supported": [], "credential_signing_alg_values_supported": [ -7 ], "credential_metadata": { "claims": [ { "path": [ "vc", "credentialSubject", "firstName" ], "mandatory": true, "display": [ { "name": "First Name", "locale": "en-US" } ] } ] } }, "b068c060-cc72-4758-9526-92d29edb821f": { "format": "cwt", "id": "b068c060-cc72-4758-9526-92d29edb821f", "scope": "cwt:TestCredential", "type": "TestCredential", "cryptographic_binding_methods_supported": [], "credential_signing_alg_values_supported": [ -7 ], "credential_metadata": { "claims": [ { "path": [ "firstName" ], "mandatory": true, "display": [ { "name": "First Name", "locale": "en-US" } ] } ] } }, "a1b2c3d4-e5f6-4789-abcd-ef0123456789": { "format": "mso_mdoc", "doctype": "org.iso.18013.5.1.mDL.T", "scope": "mso_mdoc:TestCredential", "id": "a1b2c3d4-e5f6-4789-abcd-ef0123456789", "cryptographic_binding_methods_supported": [ "mso" ], "credential_signing_alg_values_supported": [ -7 ], "proof_types_supported": { "jwt": { "proof_signing_alg_values_supported": [ "ES256" ] } }, "credential_metadata": { "claims": [ { "path": [ "org.iso.18013.5.1", "firstName" ], "mandatory": true, "display": [ { "name": "First Name", "locale": "en-US" } ] } ], "display": [ { "name": "Test Mobile Credential", "logo": { "uri": "https://example.com/logo.png", "alt_text": "Example Logo" }, "locale": "en-US", "background_color": "#FFFFFF", "text_color": "#000000" } ] } } }, "mdoc_iacas_uri": "http://example.com", "credential_response_encryption": { "alg_values_supported": [ "HPKE-7" ], "enc_values_supported": [ "A256GCM" ], "encryption_required": false }, "credential_request_encryption": { "jwks": { "keys": [ { "kty": "EC", "kid": "kid", "use": "enc", "crv": "P-256", "alg": "HPKE-7", "x": "YO4epjifD-KWeq1sL2tNmm36BhXnkJ0He-WqMYrp9Fk", "y": "Hekpm0zfK7C-YccH5iBjcIXgf6YdUvNUac_0At55Okk" } ] }, "enc_values_supported": [ "A256GCM" ], "encryption_required": false }}How would you rate this page?
Last updated on