Learn

Credential issuance

Specifies paths and operations for issuing credentials as part of an OID4VCI workflow.

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
Request
query Parameters
response_type
required
string

The response type, which must be 'code'.

Value: "code"
client_id
required
string

The client identifier.

redirect_uri
required
string

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

scope
required
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
required
string

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

Value: "S256"
code_challenge
required
string

A high entropy random challenge generated by the client.

Responses
302

Redirection to client application with authorization code

400

Bad Request. The request was malformed or missing required parameters.

401

Unauthorized. The client is not recognized by authorization server.

403

Forbidden. The client is recognized by authorization server but is not allowed to access this resource.

500

Internal Server Error. An unexpected error occurred.

get/v1/oauth/authorize
Request samples 
Response samples 
application/json
{
  • "code": "string",
  • "type": "string",
  • "message": "string",
  • "details": [
    ]
}
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
    • 



Request 
Request Body schema: application/x-www-form-urlencoded
One of:
client_id
required
string
The client identifier.


 
grant_type
required
string
The grant type, which must be 'authorization_code'.


 Value: "authorization_code"  
redirect_uri
required
string
The redirect URI that was used in the authorization request.


 
code
required
string
The authorization code obtained from the authorization endpoint.


 
code_verifier
required
string
SHA256 hash of the code_challenge in the authorization request.


 
Responses 
200
Access token successfully returned.


400
Bad Request. The request was malformed or missing required parameters.


401
Unauthorized. The client is not recognized by authorization server.


403
Forbidden. The client is recognized by authorization server but is not allowed to access this resource.


500
Internal Server Error. An unexpected error occurred.


post/v1/oauth/token
Request samples 
application/x-www-form-urlencoded
client_id=string&grant_type=authorization_code&redirect_uri=string&code=string&code_verifier=string
Response samples 
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 0,
  • "scope": "string"
}
Issue a verifiable credential
Issues a verifiable credential to a subject as part of the OpenID4VCI protocol.


See https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-credential-endpoint


Analytic events


    

  • OPENID_CREDENTIAL_START
    • 

  • OPENID_CREDENTIAL_SUCCESS
    • 

  • OPENID_CREDENTIAL_FAIL
    • 



SecuritybearerAuthOpenIdCredentials 
Request 
Request Body schema: application/json
One of:
format
required
string
Credential format, always ldp_vc for JSON credentials.


 Value: "ldp_vc"  
required
object
 
object
JSON object containing proof of possession of the key material the issued Credential shall be bound to.


 
Responses 
200
Credential issued


post/v1/openid/credential
Request samples 
application/json
{
  • "format": "ldp_vc",
  • "credential_definition": {},
  • "proof": {
    }
}
Response samples 
application/json
{}
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
    • 



Roles:  ["Admin","Issuer"]
SecuritybearerAuthOpenIdCredentials 
Request 
Request Body schema: application/json
credentials
required
Array of strings
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.


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


 
Responses 
200
Credential offer URI created


post/v1/openid/offers
Request samples 
application/json
{
  • "credentials": [
    ],
  • "request_parameters": {
    }
}
Response samples 
application/json
{
  • "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"
}
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.


Responses 
200
OpenID4VCI credential issuer metadata retrieved


get/.well-known/openid-credential-issuer
Request samples 
curl --request GET \
  --url https://{tenantName}.{region}.mattr.global/.well-known/openid-credential-issuer \
  --header 'Accept: application/json'

Response samples 
application/json
{
  • "issuer": "http://example.com",
  • "authorization_endpoint": "http://example.com",
  • "token_endpoint": "http://example.com",
  • "scopes_supported": [
    ],
  • "response_types_supported": [
    ],
  • "response_modes_supported": [
    ],
  • "grant_types_supported": [
    ],
  • "code_challenge_methods_supported": [
    ],
  • "credential_issuer": "http://example.com",
  • "credential_endpoint": "http://example.com",
  • "credentials_supported": [
    ],
  • "mdoc_iacas_uri": "http://example.com"
}
Create a Pre-Authorized Code credential offer
Generate a new OpenID4VCI Pre-Authorized Code credential offer.


Analytic events


    

  • OPENID_PRE_AUTHORIZED_OFFER_CREATE_START
    • 

  • OPENID_PRE_AUTHORIZED_OFFER_CREATE_SUCCESS
    • 

  • OPENID_PRE_AUTHORIZED_OFFER_CREATE_FAIL
    • 



Roles:  ["Admin","Issuer"]
SecuritybearerAuthOpenIdCredentials 
Request 
Request Body schema: application/json
credentials
required
Array of strings
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.


 
userId
string
Unique system generated identifier to reference the user for this offer. This can be obtained by searching for a user. If not provided, a new user entity will be created.


 
object
Configure whether a second-factor transaction code is required for this offer. If a configuration is provided, a code will be generated for the offer, and the end user must submit it during credential retrieval.


 
claims
object
Additional user claims that are available during credential issuance for this offer.


 
claimsToPersist
Array of strings
List of claims to persist from the provided claims to MATTR VII. By default no claim values are persisted.


 
object
Specifies when the offer will expire. Once the offer expires, the user can no longer use it to claim a credential, and a new offer must be generated. The expiration period can include any combination of minutes and seconds. By default, the offer expires in 5 minutes, and the maximum allowed duration is 10 minutes.


 
Responses 
200
Credential offer created


post/v1/openid/offers/pre-authorized
Request samples 
application/json
{
  • "credentials": [
    ],
  • "userId": "string",
  • "transactionCodeConfiguration": {
    },
  • "claims": {
    },
  • "claimsToPersist": [
    ],
  • "expiresIn": {
    }
}
Response samples 
application/json
{
  • "id": "string",
  • "userId": "string",
  • "uri": "openid-credential-offer://?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Fexample.com%22%2C%22credentials%22%3A%5B%222edaf985-fcc2-4448-9c8e-a04c6c7351c2%22%5D%2C%22grants%22%3A%7B%22urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Apre-authorized_code%22%3A%7B%22pre-authorized_code%22%3A%22stukD6lg9c9tQ3jUCa32wVi1HI%2BQIVsFK%2FQPvC2CHRs%3D%22%2C%22tx_code%22%3A%7B%22length%22%3A6%2C%22input_mode%22%3A%22numeric%22%2C%22description%22%3A%22Please%20provide%20the%20one-time%20code%20that%20was%20sent%20via%20e-mail%22%7D%7D%7D%7D",
  • "expiresAt": "2025-05-01T00:01:00.000Z",
  • "transactionCode": 493536
}
➔ Next to Users