MATTR Learn

Authorization

bearerAuthOpenIdCredentials

AuthorizationBearer <token>

In: header

Request Body

application/json

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.

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"
    ]
  }'

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"

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 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:

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?unknown

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'

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 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:

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..."
      ]
    }
  }'

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"
})

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`