light-mode-image
Learn
Credential issuance

API Reference

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

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
Empty

Issue a verifiable credential

POST/v1/openid/credential

Authorization

AuthorizationBearer <token>

In: header

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.

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

How would you rate this page?

End-to-End Encryption

Previous Page

Overview

Next Page

On this page

Request authorization for access to resourcesExchange authorization code for access tokenIssue a verifiable credential