MATTR Learn

Authorization

bearerAuthOpenIdCredentials

AuthorizationBearer <token>

In: header

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.

Response Body

`application/json`

curl -X POST "https://example.vii.au01.mattr.global/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

GET/v1/oauth/authorize

Query Parameters

response_type*string

The response type, which must be 'code'.

Value in"code"

client_id*string

The client identifier.

redirect_uri*string

The URI to which the authorization server will redirect the user-agent with the authorization code.

scope*string

The scope of the access request.

state?string

An opaque value used by the client to maintain state between the request and callback.

code_challenge_method*string

The method used to derive the code_challenge, which must be 'S256'.

Value in"S256"

code_challenge*string

A high entropy random challenge generated by the client.

Response Body

`application/json`

`text/plain`

curl -X GET "https://example.vii.au01.mattr.global/v1/oauth/authorize?response_type=code&client_id=string&redirect_uri=string&scope=string&code_challenge_method=S256&code_challenge=string"

Empty

{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}

"Unauthorized"

Empty

Exchange authorization code for access token

POST/v1/oauth/token

Header Parameters

DPoP?string

DPoP proof JWT. A signed JWT that demonstrates proof-of-possession of a private key.

DPoP is offered as a closed beta preview feature and is not generally available yet. If you are interested in trying this feature, please contact us

When to use:

Token endpoint: Required when dpop_jkt was 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 be ES256
typ: Must be dpop+jwt
jwk: Public key (JWK format)

Payload:

htu: HTTP URI of the target endpoint
htm: HTTP method (e.g., POST)
jti: Unique identifier for this DPoP proof
iat: Unix timestamp when the DPoP proof was created
ath: Optional base64url-encoded SHA-256 hash of the access_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?string

OAuth-Client-Attestation-PoP proof JWT that demonstrates:

Proof-of-possession of a private key from a wallet instance
Binding to OAuth-Client-Attestation JWT

OAuth-Client-Attestation-PoP and client attestation in general are offered as closed beta preview features and are not generally available yet. If you are interested in trying this feature, please contact us

When to use:

Token endpoint: When OAuth Client has client attestation enabled with dpopRequired set 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 be ES256
typ: Must be oauth-client-attestation-pop+jwt

Payload:

aud: HTTP Host of the target endpoint
jti: Unique identifier for this OAuth-Client-Attestation-PoP proof
iat: 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?string

JWT 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.

Client Attestation support is currently offered as a tech preview. As such, functionality may be limited, may not work in all scenarios, and could change or break without prior notice.

When to use:

When client attestation is configured for this client_id

Header:

alg: Must be ES256
typ: Must be oauth-client-attestation+jwt
x5c: 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 request
client_instance_id: Optional identifier to represent the client/app instance.
iat: Unix timestamp when the token was created
exp: Unix timestamp when the token will expire
cnf.jwk: JWK public key from the client instance that the authorization server uses to verify the signature of subsequent DPoP or PoP proofs.

Request Body

application/x-www-form-urlencoded

client_id*string

The client identifier.

grant_type*string

The grant type, which must be 'authorization_code'.

Value in"authorization_code"

redirect_uri*string

The redirect URI that was used in the authorization request.

code*string

The authorization code obtained from the authorization endpoint.

code_verifier*string

SHA256 hash of the code_challenge in the authorization request.

Response Body

`application/json`

`text/plain`

curl -X POST "https://example.vii.au01.mattr.global/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"
}

{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}

"Unauthorized"

Empty

DPoP is offered as a closed beta preview feature and is not generally available yet. If you are interested in trying this feature, please contact us

When to use:

Token endpoint: Required when dpop_jkt was 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 be ES256
typ: Must be dpop+jwt
jwk: Public key (JWK format)

Payload:

htu: HTTP URI of the target endpoint
htm: HTTP method (e.g., POST)
jti: Unique identifier for this DPoP proof
iat: Unix timestamp when the DPoP proof was created
ath: Optional base64url-encoded SHA-256 hash of the access_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.

Request Body

credential_configuration_id*string

Credential configuration identifier.

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.

Response Body

curl -X POST "https://example.vii.au01.mattr.global/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

GET/.well-known/openid-credential-issuer

Response Body

`application/json`

fetch("https://example.vii.au01.mattr.global/.well-known/openid-credential-issuer", {  method: "GET"})

{
  "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": "string",
      "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
  }
}

API Reference

Create Credential Offer

Authorization

Request Body

Response Body

`application/json`

Request authorization for access to resources

Query Parameters

Response Body

`application/json`

`text/plain`

Exchange authorization code for access token

Header Parameters

Request Body

Response Body

`application/json`

`application/json`

`text/plain`

Issue a verifiable credential

Authorization

Header Parameters

Request Body

Response Body

Retrieve issuer metadata

Response Body

`application/json`

On this page

API Reference

200application/json

302

400application/json

401text/plain

403

500

200application/json

400application/json

401text/plain

403

500

200

Response to issue a JSON credential

Response to issue a Semantic CWT credential

Response to issue a CWT credential

Response to issue an mDocs credential

Response to issue a JSON credential (deprecated)

Response to issue a Semantic CWT credential (deprecated)

Response to issue a CWT credential (deprecated)

Response to issue an mDocs credential (deprecated)

200application/json

On this page

`application/json`

`application/json`

`text/plain`

`application/json`

`application/json`

`text/plain`

`application/json`