light-mode-image
Learn
Authorization Code flow

API Reference

Create Credential Offer

Create an Authorization Code credential offer

Returns an OpenID4VCI credential offer URI. See https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#section-10.1

Analytic events

  • OPENID_OFFER_CREATE_START
  • OPENID_OFFER_CREATE_SUCCESS
  • OPENID_OFFER_CREATE_FAIL
POST/v1/openid/offers

Authorization

AuthorizationBearer <token>

In: header

Request Body

credentialsarray<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?object

Specifies a list of additional request parameters that the wallet can include in the authentication request.

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

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

Analytic events

  • OPENID_AUTHORIZE_START
  • OPENID_AUTHORIZE_SUCCESS
  • OPENID_AUTHORIZE_FAIL
GET/v1/oauth/authorize

Query Parameters

response_typestring

The response type, which must be 'code'.

Value in"code"
client_idstring

The client identifier.

redirect_uristring

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

scopestring

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_methodstring

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

Value in"S256"
code_challengestring

A high entropy random challenge generated by the client.

curl -X GET "https://example.vii.au01.mattr.global/v1/oauth/authorize?response_type=code&client_id=string&redirect_uri=string&scope=string&state=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

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.

Analytic events

  • OPENID_TOKEN_START
  • OPENID_TOKEN_SUCCESS
  • OPENID_TOKEN_FAIL
POST/v1/oauth/token

Request Body

client_idstring

The client identifier.

grant_typestring

The grant type, which must be 'authorization_code'.

Value in"authorization_code"
redirect_uristring

The redirect URI that was used in the authorization request.

codestring

The authorization code obtained from the authorization endpoint.

code_verifierstring

SHA256 hash of the code_challenge in the authorization request.

grant_typestring

The grant type, which must be 'urn:ietf:params:oauth:grant-type:pre-authorized_code'.

Value in"urn:ietf:params:oauth:grant-type:pre-authorized_code"
pre-authorized_codestring

The pre-authorized code obtained from the pre-authorized offer URI

tx_code?string

The transaction code obtained from the pre-authorized offer URI.

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": "string",
  "token_type": "Bearer",
  "expires_in": 0,
  "scope": "string"
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}
"Unauthorized"
Empty
Empty

Issue a verifiable credential

Issue a verifiable credential

Issues a credential to a holder upon presentation of a valid access token, as per OpenID4VCI.

The valid access token must be provided in the following header format: Authorization: Bearer <access_token>.

Analytic events

  • OPENID_CREDENTIAL_START
  • OPENID_CREDENTIAL_SUCCESS
  • OPENID_CREDENTIAL_FAIL
POST/v1/openid/credential

Authorization

AuthorizationBearer <token>

In: header

Request Body

formatstring

Credential format, always ldp_vc for JSON credentials.

Value in"ldp_vc"
credential_definitionobject
proof?object

JSON object containing proof of possession of the key material the issued Credential shall be bound to.

formatstring

Credential format, always cwt for CWT credentials.

Value in"cwt"
typestring
formatstring

Credential format, always cwt_vc for Semantic CWT credentials.

Value in"cwt_vc"
typesarray<string>
formatstring

Credential format, always mso_mdoc for mDocs.

Value in"mso_mdoc"
doctypestring

The document type identifier for the credential, as defined in ISO/IEC 18013-5:2021.

proof?object

JSON object containing proof of possession of the key material the issued credential shall be bound to.

curl -X POST "https://example.vii.au01.mattr.global/v1/openid/credential" \  -H "Content-Type: application/json" \  -d '{    "format": "ldp_vc",    "credential_definition": {      "type": [        "VerifiableCredential",        "AlumniCredential"      ],      "@context": [        "https://www.w3.org/2018/credentials/v1"      ]    },    "proof": {      "proof_type": "jwt",      "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."    }  }'
{
  "credential": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://www.w3.org/2018/credentials/examples/v1"
    ],
    "type": [
      "VerifiableCredential",
      "AlumniCredential"
    ],
    "issuer": {
      "id": "did:web:organization.com",
      "name": "Example University",
      "logoUrl": "https://example.edu/img/logo.png",
      "iconUrl": "https://example.edu/img/icon.png"
    },
    "credentialBranding": {
      "backgroundColor": "#B00AA0",
      "watermarkImageUrl": "https://example.edu/img/watermark.png"
    },
    "issuanceDate": "2020-05-02T12:06:29.156Z",
    "credentialStatus": {
      "id": "https://tenant.vii.mattr.global/v1/revocation-lists/cc641396-3750-43c8-b8b8-f30d74eb3fb3#1",
      "type": "RevocationList2020Status",
      "revocationListIndex": 1,
      "revocationListCredential": "https://tenant.vii.mattr.global/v1/revocation-lists/cc641396-3750-43c8-b8b8-f30d74eb3fb3"
    },
    "credentialSubject": {
      "givenName": "Jamie",
      "familyName": "Doe",
      "alumniOf": "Example University"
    },
    "proof": {
      "type": "Ed25519Signature2018",
      "created": "2020-05-02T12:06:29Z",
      "jws": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
      "proofPurpose": "assertionMethod",
      "verificationMethod": "did:web:organization.com"
    },
    "name": "Alumni Credential",
    "description": "This credential shows that the person has attended the mentioned university."
  },
  "format": "ldp_vc"
}

Retrieve issuer metadata

Retrieve OpenID4VCI issuer metadata

Returns OpenID4VCI issuer metadata. This is the standard OpenID4VCI 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 OpenID4VCI capabilities.

GET/.well-known/openid-credential-issuer
curl -X GET "https://example.vii.au01.mattr.global/.well-known/openid-credential-issuer"
{
  "issuer": "http://example.com",
  "authorization_endpoint": "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": "string",
      "cryptographic_suites_supported": "string"
    }
  ],
  "mdoc_iacas_uri": "http://example.com"
}

How would you rate this page?

Tutorial

Previous Page

Overview

Next Page

On this page

Create Credential OfferRequest authorization for access to resourcesExchange authorization code for access tokenIssue a verifiable credentialRetrieve issuer metadata