API Reference
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
Analytics Events
response_type*"code"The response type, which must be 'code'.
"code"client_id*stringThe client identifier.
redirect_uri*stringThe URI to which the authorization server will redirect the user-agent with the authorization code.
scope*stringThe scope of the access request.
state?stringAn opaque value used by the client to maintain state between the request and callback.
code_challenge_method*"S256"The method used to derive the code_challenge, which must be 'S256'.
"S256"code_challenge*stringA high entropy random challenge generated by the client.
Redirection to client application with authorization code
curl -X GET "https://example.com/v1/oauth/authorize?response_type=code&client_id=string&redirect_uri=string&scope=string&code_challenge_method=S256&code_challenge=string"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.
When the session binds claim sets, authorization_details is determined by the credential issuer. A request that includes authorization_details is rejected with invalid_authorization_details.
Claim set identifiers are offered as an open beta preview feature and are not generally available yet. They are available on all tenants, and their behavior may change in a way that breaks existing integrations before they become generally available.
Analytics Events
DPoP?stringDPoP proof JWT. A signed JWT that demonstrates proof-of-possession of a private key.
When to use:
- Token endpoint: Required when
dpop_jktwas 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 beES256typ: Must bedpop+jwtjwk: Public key (JWK format)
Payload:
htu: HTTP URI of the target endpointhtm: HTTP method (e.g.,POST)jti: Unique identifier for this DPoP proofiat: Unix timestamp when the DPoP proof was createdath: Optional base64url-encoded SHA-256 hash of theaccess_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?stringOAuth-Client-Attestation-PoP proof JWT that demonstrates:
- Proof-of-possession of a private key from a wallet instance
- Binding to OAuth-Client-Attestation JWT
When to use:
- Token endpoint: When OAuth Client has client attestation enabled with
dpopRequiredset 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 beES256typ: Must beoauth-client-attestation-pop+jwt
Payload:
aud: HTTP Host of the target endpointjti: Unique identifier for this OAuth-Client-Attestation-PoP proofiat: 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?stringJWT 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.
When to use:
- When client attestation is configured for this client_id
Header:
alg: Must beES256typ: Must beoauth-client-attestation+jwtx5c: 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 requestclient_instance_id: Optional identifier to represent the client/app instance.iat: Unix timestamp when the token was createdexp: Unix timestamp when the token will expirecnf.jwk: JWK public key from the client instance that the authorization server uses to verify the signature of subsequent DPoP or PoP proofs.
application/x-www-form-urlencoded- body
client_id*stringThe client identifier.
grant_type*"authorization_code"The grant type, which must be 'authorization_code'.
"authorization_code"redirect_uri*stringThe redirect URI that was used in the authorization request.
code*stringThe authorization code obtained from the authorization endpoint.
code_verifier*stringSHA256 hash of the code_challenge in the authorization request.
Access token successfully returned.
application/json- response
access_token*stringThe access token issued by the authorization server.
token_type*"Bearer"The type of the token, which is always 'Bearer'.
"Bearer"expires_in*integerThe number of seconds until the token expires.
scope*stringThe scope of the access token.
authorization_details?array<>The credentials this token can be used to retrieve, one entry per credential configuration. Only returned when the session binds claim sets.
Each credential_identifiers value represents the credential for a single claim set, and is provided as credential_identifier when requesting a credential.
Claim set identifiers are offered as an open beta preview feature and are not generally available yet. They are available on all tenants, and their behavior may change in a way that breaks existing integrations before they become generally available.
curl -X POST "https://example.com/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", "authorization_details": [ { "type": "openid_credential", "credential_configuration_id": "707e920a-f342-443b-ae24-6946b7b5033e", "credential_identifiers": [ "c3d4e5f6-a7b8-9012-cdef-123456789012", "d4e5f6a7-b8c9-0123-def1-234567890123" ] } ]}Issue a verifiable credential
Issues a credential to a holder upon presentation of a valid access token, as per OID4VCI. Supports encrypted and non-encrypted credential issuance.
For non-encrypted credential issuance the valid access token must be provided in one of the following header formats:
Bearer
- Authorization:
Bearer <access_token>. - Content-Type:
application/json - Body:
<credential request payload>
OR
DPoP Only required when using DPoP-bound access tokens.
- Authorization:
DPoP <access_token>. - DPoP:
<dpop_token> - Content-Type:
application/json - Body:
<credential request payload>
For encrypted credential issuance, contact us to configure how your MATTR VII enforces request and/or response encryption, and then:
- For request encryption,
Content-Typemust be set toapplication/jwtand the payload must be JWE formatted. - For response encryption, include the
credential_response_encryptionproperty in the raw request payload to specify encryption details.
Analytics Events
AuthorizationBearer <token>OID4VCI access token presented by a holder's wallet. Use the format: Authorization: Bearer <access_token>.
The wallet obtains this token from your tenant's token endpoint during a credential issuance flow. This is not the tenant management token used by operations that require bearerAuth.
DPoP?stringDPoP proof JWT. A signed JWT that demonstrates proof-of-possession of a private key.
When to use:
- Token endpoint: Required when
dpop_jktwas 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 beES256typ: Must bedpop+jwtjwk: Public key (JWK format)
Payload:
htu: HTTP URI of the target endpointhtm: HTTP method (e.g.,POST)jti: Unique identifier for this DPoP proofiat: Unix timestamp when the DPoP proof was createdath: Optional base64url-encoded SHA-256 hash of theaccess_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.
- body
Exactly one of credential_configuration_id or credential_identifier is required.
credential_configuration_id*stringcredential_identifier?Credential IdentifierOne of the credential_identifiers values returned in the token response authorization_details, selecting the credential to issue for a single claim set.
Treat this value as opaque. It is derived by MATTR VII and does not encode the claim set identifier you supplied.
This property is mutually exclusive with credential_configuration_id, and only resolves while it remains bound to the grant. For mDocs, the same value is returned as credential_bundle_id on the credential response, so you can correlate an issued credential back to the claim set it was requested for.
Claim set identifiers are offered as an open beta preview feature and are not generally available yet. They are available on all tenants, and their behavior may change in a way that breaks existing integrations before they become generally available.
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.
Credential issued
- response
credentials*array<>curl -X POST "https://example.com/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?
Last updated on