Platform Core API (v1.1.0)

Download OpenAPI specification:Download

Introduction

The Platform Core API defines a set of capabilities that can be used to manage a tenant of the MATTR Platform.

The API can be used to manage Decentralised Identifiers, issue Credentials directly or using OpenID Connect flows, and verify Messages signed with DIDs.

Pagination

Most list operations in the API use pagination that can be controlled by a cursor method using the cursor and limit query parameters.

Example on Retrieve List of Credentials

GET https://tenant.vii.mattr.global/core/v1/credentials
?limit=100
&cursor=Y3JlYXRlZEF0PTIwMjAtMTAtMDhUMjMlM0ExMyUzQTE3Ljg5NtZGUxZWEyNzQ4MWI4
  • The nextCursor is found at the start of each returned range of credential entries and identifies the last object in the list.
  • The limit determines how many entries are returned in that request, with a maximum value of 1000.

Requesting a page after the last value in the list will return an empty data object.

{
"data": []
}

Not using a query parameter defaults the response to return the first range of credential entries with a limit of 100.

Authorization

Access to the API is granted by our authorization provider, as part of onboarding you will be provided with client credentials to make a call to the auth provider and receive a bearer token. This token is then used in an authorization header on all calls idenitfied as requiring bearerAuth (this is required for the majorty of management operations).

bearerAuth

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

clientRegistrationAuth

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "Client registration_access_token"

Security

Create API Auth Token

Authorization endpoint for gaining token used for API requests requiring bearerAuth.

You will be provided the required client_id and client_secret as part of onboarding.

Request Body schema: application/json
client_id
required
string

Client ID for your tenant

client_secret
required
string

Client seceret for your tenant

audience
required
string

Use provided value

grant_type
required
string

Use provided value

Responses

Request samples

Content type
application/json
{
  • "client_id": "htf792W4p4MedZbnoWAs51EfqUt4d2",
  • "client_secret": "d3fYDX7FjPg1D1h2viARXsolPByQ9vMfg8LHylBy8F4s5KJLB4HhHGOxxqJnSj3G",
  • "grant_type": "client_credentials"
}

Response samples

Content type
application/json
{
  • "access_token": "s2dgbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6s2dcaEROemRDf5gbRVEwTTVSVFE0TmtZME9UZzVNVEpDTlVJNFJqRTBPREExTmpZMk1qazFPQSJ9.eyJodHRwOi8vbWF0dHIvdGVuYW50LWlkIjoiZWI5ZTdiMTQtMzY2ZS00NzAxLTg4OTctMTIwZmI5MTQ0YmFjIiwiaXNzIjoiaHR0cHM6Ly9tYXR0ci1wcm9kLmF1LmF1dGgwLmNvbS8iLCJzdWIiOiJSZUhOOTJXNHA0TWVkWmJub1dBczUxRWZxVXQ0VDk2Y0BjbGllbnRzIiwiYXVkIjoiaHR0cHM6Ly9wbGF0Zm9ybS5tYXR0ci5nbG9iYWwiLCJpYXQiOjE1OTE4NDk4MTMsImV4cCI6MTU5MTkzNjIxMywiYXpwIjoiUmVITjkyVzRwNE1lZFpibm9XQXM1MUVmcVV0NFQ5NmMiLCJndHkiOiJjbGllbnQtY3JlZGVudGlhbHMifQ.kZt6mteIwNqdXO8CjqnsjENCgMV2-v7VMn2gtiqIuTNSxBZxk1OkeXERMuRcZpxqIjXi7SdHshQZ9wG_Cmrns_7bG5Pq-qiKCjDOK3pi6smvws02GmDH9nK4_el9zJ92_bDA0p4T6pT0ldcSAMya7ZwTz3-PYQ3pwCwiDEMWFXPtGilfHTBDmrzCUcanmErhZcopo8agtnozuIkbdZoKGkEdXO2J59PrAerBwIbhoYYgkreWIZtlbhGHueYj43ymDOHHl3I7s7zAuK1geJX4W3baKzTMPncUyGrHrOS6OI-ZodHs7kDhTyghJ13GxRy9ikAI3mXz79plZw0qxys2ed",
  • "expires_in": 86400,
  • "token_type": "Bearer"
}

Custom Domain

Create custom domain

A custom domain allows the display of your credentials or presentation requests to be rendered under the domain your preference as a tenant on the Mattr VII platform.

The verifiable custom domain can be mapped with that of the issuer or verifier stated in a credential or presentation and allow for the following attributes to be defined and returned:

  • Organisation Name
  • Domain Name
  • Logo
  • Home Page

Returns

On Success, the response from the endpoint always include the Custom Domain

Authorizations:
Request Body schema:

The custom domain payload

name
required
string

Name of the custom domain

logoUrl
required
string

Url for the domain logo

domain
required
string

New domain

homepage
required
string

Homepage for the url

Responses

Request samples

Content type
{}

Response samples

Content type
application/json
{}

Retrieve custom domain

Retrieve the custom domain information and it's veification status for your Mattr VII tenant.

Authorizations:

Responses

Request samples

curl --request GET \
  --url https://tenant.vii.mattr.global/core/v1/config/domain \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{}

Delete custom domain

Delete the custom domain.

By deleting your existing custom domain it will break the linkage with any credentials issued under the custom domain, in turn causing issues when holders of those credentials go to present them.

Authorizations:

Responses

Request samples

curl --request DELETE \
  --url https://tenant.vii.mattr.global/core/v1/config/domain \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": [
    ]
}

Update custom domain

Update the custom domain.

Follows the same structure as the Create a Custom Domain endpoint.

Authorizations:
Request Body schema: application/json
id
string
name
required
string

Name of the custom domain

logoUrl
required
string

Url for the domain logo

domain
required
string

New domain

homepage
required
string

Homepage for the url

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Verify custom domain

Verifies that you have control of the custom domain by examining the TXT record of the domain.

Authorizations:

Responses

Request samples

curl --request POST \
  --url https://tenant.vii.mattr.global/core/v1/config/domain/verify \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN' \
  --data '{}'

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": [
    ]
}

DIDs

Well known DID configuration

Returns a list of Decentralized Identifier (DID) Configuration entries from the tenant.

See https://identity.foundation/.well-known/resources/did-configuration/

These entries are automatically configured for all DIDs created by the tenant and is used for any party wanting to establish the relationship between domain ownership and the DIDs by exposing cryptographic proofs.

This endpoint is unprotected, public facing and can be determinisically found at the root of the tenant subdomian or alias by any party wishing to discover the domain to DID relationship.

Responses

Request samples

curl --request GET \
  --url https://tenant.vii.mattr.global/.well-known/did-configuration \
  --header 'Accept: application/json'

Response samples

Content type
application/json
{
  • "entries": [
    ]
}

Resolve a DID

Resolves the DID provided in the path to its DID Document from the DID method and method identifier. The DID Document may contain cryptographic material like a public key and service endpoints.

Example:

did:sov:1234556 - will be referenced on the Sovrin network did:key:z6Mkjr7vfzBfamiN6Wi6cyQUgTq6CEMXP1MzWQawsUEXJoa9 - the public key is encapsulated in the DID

Returns

The DID Document is returned along with meta-data already held about the DID by the tenant;

  • Registration Status: Given there can be a lag in writing on-ledger DIDs this status will be updated over a short timeframe (usually within 10 minutes).
  • Registered: Timestamp of registration.
  • Keys: A reference to the Keys in a KMS
Authorizations:
path Parameters
id
required
string <uuid>

Issuer ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f

Responses

Request samples

curl --request GET \
  --url https://tenant.vii.mattr.global/core/v1/dids/did:key:z6Mkjr7vfzBfamiN6Wi6cyQUgTq6CEMXP1MzWQawsUEXJoa9 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "didDocument": {
    },
  • "registrationStatus": "COMPLETED",
  • "localMetadata": {
    }
}

Delete a DID

Delete a DID

Authorizations:
path Parameters
id
required
string <uuid>

Issuer ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f

Responses

Request samples

curl --request DELETE \
  --url https://tenant.vii.mattr.global/core/v1/dids/did:key:z6Mkjr7vfzBfamiN6Wi6cyQUgTq6CEMXP1MzWQawsUEXJoa9 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "code": "NotFound",
  • "message": "Resource Not Found"
}

Retrieve a list of DIDs

Returns a list of all DIDs (Decentralized Identifiers) managed by the tenant and their associated meta-data.

Authorizations:
query Parameters
limit
number [ 1 .. 1000 ]
Default: 100

Range size of the list, default 100

Example: limit=2
cursor
string

Starting point for the list

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

curl --request GET \
  --url https://tenant.vii.mattr.global/core/v1/dids \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",
  • "data": [
    ]
}

Create a DID

Takes a supported DID Method and generates keys and associated information for a new DID and registers the DID Document if applicable.

Methods supported:

  • key
  • web
  • sov

During a trial any did:sov DIDs will not reside on the Sovrin MainNet, and when migrating to the MainNet any sov DIDs will be removed. Any did:sov DIDs created using this endpoint should be considered as experimental as well as any credentials created using them.

Creating did:key

A DID with a DID method of key can be created as follows.

  • {"method": "key", "options": {"keyType": "ed25519"}}
  • {"method": "key", "options": {"keyType": "bls12381g2"}}

If no options are provided, a DID will be created with an ed25519 key type.

If the key type in options is set to bls12381g2 a DID will be created with a BLS key type which supports BBS+ signatures for issuing ZKP-enabled credentials.

A DID created with an experimental bls12381g2 key type can only be used for issuing credentials.

Creating did:web

A DID with a DID method of web can be created as follows.

  • {"method": "web", "options": {"domain": "mattr.global"}}

The returned initial DID Document then needs to be hosted so that it is accessible from the domain provided in the options, e.g. https://mattr.global/.well-known/did.json.

When the DID Document is not available for download from the domain, the Registration Status of the DID is PROCESSING.

Once the DID Document can be downloaded from the domain, the Registration Status will be COMPLETED.

Note that the tenant will be able to prove ownership of the keys associated with the did:web DID Document through the well-known endpoint, i.e. https://tenant.vii.mattr.global/.well-known/did-configuration, while the DID Document hosted on the domain links the DID to a domain.

Creating did:sov

A DID with a DID method of sov can be created as follows.

  • {"method": "sov"}

The Registration Status of the DID is updated over a short timeframe due to the lag incurred in registering the DID Document, which may take up to 10 minutes.

During a trial DID Documents are anchored on a private Indy pool not the Sovrin MainNet. Please contact us to discuss further options.

Returns

The DID, associated metadata and registration status.

Unsupported Methods result in a 400 response with an "Invalid value" message.

Authorizations:
Request Body schema: application/json

Options for creating the decentralized identifier

method
required
string
Enum: "key" "web" "sov"
options
object non-empty

To define a key type for a did:key or to define a domain for did:web

Responses

Request samples

Content type
application/json
{
  • "method": "key",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "did": "did:key:z6MkrYVmyqSA93o4B1GwERM8kaQDMAUKAFV2TC3weQKeg9Gq",
  • "registrationStatus": "COMPLETED",
  • "localMetadata": {
    }
}

Credentials

Create a verifiable credential

Creates a Verifiable Credential (VC or just Credential) in a JSON-LD format adhering to the W3C VC Data Model spec.

Creating the Payload:

The values required by the operation are validated where available and used to construct the Verifiable Credential.

The Credential is issued using JSON-LD with linked data proofs, the type values of the Credential and the Subject Claims must be represented by a schema in @context.

The schema https://www3.org/2018/credentials/v1 is always required in addition any @context values, so that the Credential can be referenced.

The type value of VerifiableCredential must be used as the first value in the array to conform to the W3C VC Data Model spec.

Subject Identifiers

In general, the Subject identifier in the subjectId field should have been authentically bound to the subject and authenticated against the information used in the claims, for example by using an OpenID Connect authentication flow or another mechanism including out-of-band processes.

Credentials may be issued without subject identifiers, this covers uses-cases, where the credential cannot or does not need to be adequately bound to a Subject DID and may be treated as a bearer credential or reissued at a later time once the credential can be bound.

ZKP-enabled BBS+ credential:

If you wish to issue a ZKP-enabled Verifiable Credential, the provided issuer id must be a did:key with a key type of bls12381g2. The platform will automatically detect this capability and issue a ZKP-enabled BBS+ credential. Note that the schema https://w3c-ccg.github.io/ldp-bbs2020/context/v1 will automatically be added to the @context in the credential.

During Preview this feature is experimental. It may change over time and may require credentials to be reissued.

Credential meta-data:

Setting the persist value to true will store the entire credential contents as well as the meta-data on the platform. If set to false only the credential meta-data is held on the platform:

  • id
  • tag (optional)
  • credentialStatus (optional)
  • issuanceDate

The optional tag value can be used to externally reference the issued credential.

Returns

On success, the Verifiable Credential is always provided in the response along with meta-data. Subject bound credential should be delivered to the intended subject.

Authorizations:
Request Body schema: application/json

The credential payload

@context
required
Array of strings non-empty

Additional to any JSON-LD contexts 'https://www.w3.org/2018/credentials/v1' is always required.

subjectId
string non-empty

Generally a DID, identifier of who/what the subject is

tag
string [ 1 .. 1024 ] characters

An optional tag to filter by, will not be part of the issued credential

required
string or Array of strings

Type for the Credential, VerifiableCredential must be presented

claims
required
object non-empty

Each value is a claim that is defined by one of the JSON-LD schemas.

required
object

Includes Issuer id (DID) and domain name

persist
boolean

Flag to indicate whether the full credential should be stored in platform

revocable
boolean

Flag to indicate if the credential needs to support revocation

name
string

Name of the credential (requires v2 data model)

description
string

Description of the credential (requires v2 data model)

Responses

Request samples

Content type
application/json
{
  • "subjectId": "did:key:z6Mkvji7zrwyFATXUzGNBSCnrPaZy7H3BWUnihrHvZdkEd9y",
  • "type": [
    ],
  • "claims": {
    },
  • "issuer": {
    },
  • "persist": true,
  • "tag": "identifier123",
  • "revocable": true
}

Response samples

Content type
application/json
{}

Retrieve list of credential data

Returns a list of all credential data stored in the tenant.

In the list

Inside the data array, there is an body for each credential issued on the platform, in addition to the id the body will contain optionally added meta-data and may contain the entire credential contents if persist was invoked during credential creation.

Credentials issued via the OIDC Bridge are set not to be persisted.

Pagination

Pagination can be controlled by a cursor method using the cursorand limit query parameters. The nextCursor is found at the start of each returned range of credential entries and the limit determines how many entries are returned in that request, with a maximum value of 1000.

Not using a query parameter defaults the response to return the first range of credential entries with a limit of 100.

The optional tag filter or the Credential type can be used to retrieve credential data.

Authorizations:
query Parameters
tag
string

The optional external reference to filter on

Example: tag=identifier123
type
string

The optional credential type to filter on

Example: type=AlumniCredential
limit
number [ 1 .. 1000 ]

Range size of returned credential entries, default 100

Example: limit=2
cursor
string

Starting point for the range of credential entries

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

curl --request GET \
  --url https://tenant.vii.mattr.global/core/v1/credentials \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",
  • "data": [
    ]
}

Retrieve credential data

Get data for a previously created credential using its ID.

In addition to the id the body will contain optionally added meta-data and may contain the entire credential contents if persist was invoked during credential creation.

Credentials issued via the OIDC Bridge do not have their contents persisted.

Authorizations:
path Parameters
id
required
string

Credential ID

Responses

Request samples

curl --request GET \
  --url https://tenant.vii.mattr.global/core/v1/credentials/873277c0-a162-11ea-8a1d-a111119347e6 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
Example
{}

Remove credential data

Remove all stored credential data from the tenant using its ID.

The entire entry including meta-data and the credential contents is removed from the system and cannot be recovered.

Authorizations:
path Parameters
id
required
string

Credential ID

Responses

Request samples

curl --request DELETE \
  --url https://tenant.vii.mattr.global/core/v1/credentials/873277c0-a162-11ea-8a1d-a111119347e6 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": [
    ]
}

Verify a credential

Send any JSON-LD Verifiable Credential that conforms to the W3C Verifiable Credentials data model to perform verification checks and return a response:

  • Issuer DID can be resolved
  • JSON-LD context is valid for subject claims
  • Proof is valid & the credential has not been tampered with
  • Is not in a revoked status on a RevocationList2020 This endpoint can be used to check any Credential issued by any service provider.
Authorizations:
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
Example
{
  • "verified": true
}

Revocation

Set credential revocation status

A credential can be revoked by setting the revocation status.

Authorizations:
path Parameters
id
required
string <uuid>

Credential ID

Example: a80a5e7e-1972-4be6-8a4e-2adf09badf24
Request Body schema: application/json

Setting the revocation status

isRevoked
required
boolean

true if the credential is revoked, false otherwise

Responses

Request samples

Content type
application/json
{
  • "isRevoked": true
}

Response samples

Content type
application/json
Example
{
  • "code": "NotFound",
  • "message": "Validation Error",
  • "details": [
    ]
}

Retrieve credential revocation status

Retrieve the revocation status of a certain credential.

Returns

The revocation status of the credential

Authorizations:
path Parameters
id
required
string <uuid>

Credential ID

Example: a80a5e7e-1972-4be6-8a4e-2adf09badf24

Responses

Request samples

curl --request GET \
  --url https://tenant.vii.mattr.global/core/v1/credentials/a80a5e7e-1972-4be6-8a4e-2adf09badf24/revocation-status \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "isRevoked": false
}

Retrieve revocation list

Retrieve the revocation list that contains the revocation status of a number of credentials.

Returns

The revocation list

path Parameters
id
required
string <uuid>

Revocation list ID

Example: cc641396-3750-43c8-b8b8-f30d74eb3fb3

Responses

Request samples

curl --request GET \
  --url https://tenant.vii.mattr.global/core/v1/revocation-lists/cc641396-3750-43c8-b8b8-f30d74eb3fb3 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "type": [
    ],
  • "issuer": "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5",
  • "issuanceDate": "2020-05-02T12:06:29.156Z",
  • "credentialSubject": {
    },
  • "proof": {
    }
}

Create a revocation message payload

Create a payload that can form a message in the JWM format that can be used in sending notifications to subjects based on the revocation status of their issued credentials.

  • Use a DID setup on the tenant as the from value, this should be a DID with a key type suitable for messaging (not a BLS key type)
  • Include a SubjectDID as the to value - this value is only used in the message construction, it should be the same value as the intended recipient.

To send a notification to the Subject DID holder, use the payload with the /messaging/encrypt and /messaging/send endpoints.

Authorizations:
path Parameters
id
required
string <uuid>

Credential ID

Example: 873277c0-a162-11ea-8a1d-a111119347e6
Request Body schema: application/json

Create a JWM message payload

from
required
string non-empty

DID on the tenant used in a message

to
required
Array of strings

List of SubjectDIDs

Responses

Request samples

Content type
application/json
{
  • "from": "string",
  • "to": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "string",
  • "to": [
    ],
  • "from": "string",
  • "created_time": 0,
  • "body": {
    }
}

Presentations

Create a presentation template

A Presentation Request Template defines which credentials are required for presentation. This is used to create the actual Presentation Request, which is used by the Mobile Wallet to select which credential it should display to the Holder, asking for confirmation to be used in the Presentation to be sent.

Creating the payload

The domain value must always match the domain of the tenant being used.

The name value is a convenience attribute for quickly determining the intended purpose of a created template.

The Presentation Request query follows the Verifiable Presentation Request Specification.

The following query methods have been enabled:

  • Query by Example
  • Query by Frame
  • DID Auth

Query can accept an array of types, which makes is possible to construct complex presentation requests from the template, however creating a valid Presentation Template does not ensure that logically valid Presentation Request is created or that a credential holder would be able to satisfy the request.

Query by Example

This is a basic form of requesting credential information, it is possible to limit the request based on:

  • Credential Type - based on the type of the credential
  • Specific Trusted Issuer DIDs - an array of DIDs that the credential must have been issued by one of.

Query by Frame

Used primary for requesting specific claims from ZKP-enabled credentials, only the claims requested in the frame will be derived and sent in the presentation.

  • Credential Type - If an array should match the exact type used in the Credential otherwise a string is required to be VerifiableCredential.
  • CredentialSubject - request specific claims from a credential subject.
  • Specific Trusted Issuer DIDs - an array of DIDs that the credential must have been issued by one of, ensure this DID is of a BLS key type that has issued a ZKP-enabled credential.

DID Auth

The type of Template will result in a DID Auth flow resulting in just the Subject DID from the holder to be provided in the response to the Presentation Request.

  • DIDAuth

Returns

On Success, the response from the endpoint always include the Presentation Template ID, this UUID is required in OIDC Bridge Verifier instance setup and using the Verify using a Callback method. The Presentation Request endpoint uses this ID to determine the exact type of request message to create.

Authorizations:
Request Body schema: application/json

The template

domain
required
string

Must match domain of the tenant

name
required
string

Internal descriptor only

required
Array of QueryByExample (object) or QueryByFrame (object) or DIDAuth (object)

Responses

Request samples

Content type
application/json
Example
{
  • "domain": "tenant.vii.mattr.global",
  • "name": "alumni_credential_request",
  • "query": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "364b6a1b-3600-4927-a6ac-4d66aa6bbac3",
  • "domain": "tenant.vii.mattr.global",
  • "name": "alumni_credential_request",
  • "query": [
    ]
}

Retrieve a list of presentation templates

Returns a list of all Presentation Templates on the tenant.

Use the name value to determine the intended purpose of the templates.

Authorizations:
query Parameters
limit
number [ 1 .. 1000 ]
Default: 100

Range size of the list, default 100

Example: limit=2
cursor
string

Starting point for the list

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

curl --request GET \
  --url https://tenant.vii.mattr.global/core/v1/presentations/templates \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",
  • "data": [
    ]
}

Retrieve a presentation template

Retrive a Presentation Template by providing a template ID

Authorizations:
path Parameters
id
required
string

Presentation template ID

Responses

Request samples

curl --request GET \
  --url https://tenant.vii.mattr.global/core/v1/presentations/templates/364b6a1b-3600-4927-a6ac-4d66aa6bbac3 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "id": "64e45290-9980-11ea-b872-f1bee5fb328f",
  • "domain": "tenant.vii.mattr.global",
  • "name": "alumni_credential_request",
  • "query": [
    ]
}

Delete presentation template

Delete a Presentation Template

Authorizations:
path Parameters
id
required
string

Presentation template ID

Responses

Request samples

curl --request DELETE \
  --url https://tenant.vii.mattr.global/core/v1/presentations/templates/364b6a1b-3600-4927-a6ac-4d66aa6bbac3 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": [
    ]
}

Update presentation template

Update a Presentation Template using the template id.

Follows the same structure as the Create a Presentation Template endpoint.

Authorizations:
path Parameters
id
required
string

Presentation template ID

Request Body schema: application/json
id
string
domain
required
string

Must match domain of the tenant

name
required
string

Internal descriptor only

required
Array of QueryByExample (object) or QueryByFrame (object) or DIDAuth (object)

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "domain": "string",
  • "name": "string",
  • "query": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "64e45290-9980-11ea-b872-f1bee5fb328f",
  • "domain": "tenant.vii.mattr.global",
  • "name": "alumni_credential_request",
  • "query": [
    ]
}

Create a presentation request

Creates a short lived Presentation Request.

Creating the payload

A challenge can be used to collerate requests The DID is used a Verifier DID to prove the authenticity of the Request to holders Any callbackUrl provide will be called on receipt of the response to the Presentation Request. If no expiresTime is provided, a default of 5 minutes will be used.

Returns

The request object holds the Presentation Request in the form of a constructed JWM message.

The request needs to be signed and conveyed to the holder, using techniques like a QR, deeplink or encrypted and sent via a notification message.

Authorizations:
Request Body schema: application/json

The presentation request payload

challenge
string

Challenge can be used to match the response to a request

did
required
string

DID of the Verifier

templateId
required
string

Presentation Request Template id

expiresTime
number

Unix timestamp in ms after which the request will be expired

callbackUrl
string <uri>

Endpoint that will receive the Verifiable Presentation

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Create a presentation

Create a Verifiable Presentation on your tenant by providing one or more Verifiable Credentials.

To successfully create a Verifiable Presentation using this endpoint you must supply;

  • a holderDiDUrl that is controlled by the tenant

And optionally;

  • a credentials collection containing only credentials with a subject DID that is controlled by the tenant

The resulting Verifiable Presentation will contain a proof generated via the holder DID and each unique subject DID in your request.

Non-subject-bound (bearer) credentials are not supported.

Authorizations:
Request Body schema: application/json
domain
required
string
holderDidUrl
required
string <uri>
Array of objects
challenge
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "domain": "tenant.vii.mattr.global",
  • "holderDidUrl": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
  • "credentials": [],
  • "challenge": "e1b35ae0-9e0e-11ea-9bbf-a387b27c9e60"
}

Response samples

Content type
application/json
{
  • "presentation": {
    }
}

Verify a presentation

Use this endpoint to verify a Verifiable Presentation that has been generated by any platform that adheres to the W3C Verfiable Credential Data Model.

Provide a presentation in the Request

The platform ensures that the presentation conforms to the VC Data model and thus for each verifiableCredential object that is present there (if any), it will perform the following checks;

  • Issuer DID can be resolved
  • JSON-LD context is valid for subject claims
  • Proof is valid & the credential has not been tampered with
  • Is not in a revoked status on a RevocationList2020
  • The proof is valid for each subjectDID to prove ownership

Finally, the platform ensures a proof is valid for the holderDID in the presentation.

Response

If all checks are passed then the verified boolean is true Otherwise it returns false with a basic reason

Further detailed reasons for verified false responses is a future roadmap item.

Authorizations:
Request Body schema: application/json

Presentation to verify

required
object

Responses

Request samples

Content type
application/json
{
  • "presentation": {
    }
}

Response samples

Content type
application/json
{
  • "verified": true,
  • "reason": "One or more credentials are invalid"
}

Messaging

Sign a message

Creates a signed message in the form of a JWS (JSON Web Signature) using the a specific Key from the DID (Decentralized Identifier) supplied in the request.

didUrl must be a reference to a key that supports signing. Use the authentication key value from the DID Document.

{
  "didDocument": {
    "@context": "https://w3.org/ns/did/v1",
    "id": "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5#z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5",
    "authentication": [
      "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5#z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5#z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5#z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5"
    ]
  }}

Returns

A JWS in compact serialization form signed by the did supplied in the request

Authorizations:
Request Body schema: application/json

Sign message request

didUrl
required
string

The did keyId that will be used to sign the message with.

payload
required
object

A JSON Object plaintext message

Responses

Request samples

Content type
application/json
{
  • "didUrl": "did:example:abcdefghijkl#key1",
  • "payload": {
    }
}

Response samples

Content type
application/json
"eyJhbGciOiJFZERTQSIsImtpZCI6ImRpZDprZXk6ejZNa21mazNtMldIQlVxVm94SlZ3R1NQejVrYmFKNnpBMXRwN1JRWUJiUUdtczNoI3o2TWttZmszbTJXSEJVcVZveEpWd0dTUHo1a2JhSjZ6QTF0cDdSUVlCYlFHbXMzaCJ9.eyJtc2ciOiJUaGlzIGlzIGEgcGF5bG9hZCJ9.5E9qEmmSOMHLABAr4A9VzuNKFaO4EDo2GSCMoxQm9zsE7eCmEEuaAxtNhOUdd-Wvj64vqBBVl84XB1Yg7X9wBg"

Verify a message

Provide a signed payload in the form of a JWS (JSON Web Signature) that has been signed by a DID (Decentralized Identifier) and get a response indicating if the signature verification was successful and the DID that was used to originally sign the payload.

One use case for verifying a JWS with a DID is when the Mobile Wallet App sends a Request Object to an OpenID Provider as part of the Authorization Code Flow (as per https://openid.net/specs/openid-connect-core-1_0-final.html#RequestObject). The Request Object is wrapped in a JWS with a signature that is generated from the Subject DID on the mobile app. Therefore verifying the JWS proves that the mobile app has access to the private key of the Subject DID.

Returns

Indicates if the JWS payload was untampered and that the signature is valid by verifying that the kid in the JWS header is the same as the iss value in the Request Object, which could for instance be the Subject DID. The DID used is returned as both the full didUrl including fragment pointer to the DID Document and the did which can be used for Credential creation.

Authorizations:
Request Body schema: application/json

JWS to verify

jws
string

Compact form of JWS

Responses

Request samples

Content type
application/json
{
  • "jws": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Response samples

Content type
application/json
Example
{
  • "payload": "payload",
  • "didUrl": "did:key:z6Mkqh5teM4EiYkBVNPJiYhwMJ9D9MqdAi2RoNYGJspKdpWE#z6Mkqh5teM4EiYkBVNPJiYhwMJ9D9MqdAi2RoNYGJspKdpWE",
  • "did": "did:key:z6Mkqh5teM4EiYkBVNPJiYhwMJ9D9MqdAi2RoNYGJspKdpWE",
  • "verified": true
}

Encrypt a message

Encrypts a payload using a JWM format.

The senderDidUrl must be a reference to a key that supports key agreement. Use the id value from the keyAgreement list in the DID Document.

"keyAgreement": [
        {
          "id": "did:key:z6Mko4PvuwKzmjtaKTEV6ZhMSYqX5myTSe3L3Md4feiwCoua#z6LSkKk8HK73jYfUQRBHX3Qeb1Agv39qVNFn7n2PjRvjpPcy",
          "type": "X25519KeyAgreementKey2019",
          "controller": "did:key:z6Mko4PvuwKzmjtaKTEV6ZhMSYqX5myTSe3L3Md4feiwCoua",
          "publicKeyBase58": "9eZxm1JBe5wjK2oWzPthGQxD4tcinm5dEoJiEyHD71rD"
          }
      ]

Returns

Authorizations:
Request Body schema: application/json

Encryption params

senderDidUrl
required
string
recipientDidUrls
required
Array of strings
payload
required
object

Responses

Request samples

Content type
application/json
{
  • "senderDidUrl": "did:key:z6Mko4PvuwKzmjtaKTEV6ZhMSYqX5myTSe3L3Md4feiwCoua#z6LSkKk8HK73jYfUQRBHX3Qeb1Agv39qVNFn7n2PjRvjpPcy",
  • "recipientDidUrls": [
    ],
  • "payload": {}
}

Response samples

Content type
application/json
{
  • "jwe": {
    }
}

Decrypt a message

Decrypt a message where the tenant manages the Keys for the recipientDidUrl

Authorizations:
Request Body schema: application/json

Decryption params

jwe
required
string

Responses

Request samples

Content type
application/json
{
  • "jwe": "string"
}

Response samples

Content type
application/json
{
  • "payload": "string",
  • "senderDidUrl": "string",
  • "senderPublicJwk": { },
  • "recipientDidUrl": "string"
}

Send a message

Send an ecrypted JWM format DIDComm message to a DID service endpoint.

In order to successfully route messages to their intended recipients the endpoint will resolve a public DID Document and look-up the service endpoint.

This endpoint only accepts Encrypted JWM payloads to ensure that messages sent for recipients are encrypted-at-rest whilst in messaging inboxes. The JWM should be encrypted for the recipient based on a key available in the DID Document.

Authorizations:
Request Body schema: application/json
to
string

recipient DID

string or object

JWE message

Responses

Request samples

Content type
application/json
{
  • "to": "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d",
  • "message": {
    }
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": [
    ]
}

OIDC Issuer Auth

Well Known OpenId Configuration

The standard OpenID Connect Well Known configuration metadata endpoint.

This endpoint is unprotected, public facing and can be used by any party wishing to discover the OpenID Connect capabilities.

path Parameters
id
required
string <uuid>

Issuer ID

Example: 983c0a86-204f-4431-9371-f5a22e506599

Responses

Request samples

curl --request GET \
  --url https://tenant.vii.mattr.global/ext/oidc/v1/issuers/983c0a86-204f-4431-9371-f5a22e506599/.well-known/openid-configuration \
  --header 'Accept: application/json'

Response samples

Content type
application/json
{}

OIDC Issuers

Create an OIDC Issuer

Create a new OIDC Credential Issuer for this tenant.

The Credential information defines a descriptive name for the Credential to be issued as well as the issuerDid and type that the issued Credential will contain. The context is used to define the JSON-LD schema for the JSON-LD terms.

The Federated Provider details are used to obtain the values for the new credential. The OIDC provider will federate the authentication request to the OpenID Provider of the Issuer. The details of the Issuer OpenID Provider are provided in the url, scope, clientId and clientSecret attributes. If no scope is provided, the default value openid profile email will be used.

The /.well-known/openid-configuration endpoint of the federated provider needs to contain values for the authorization_endpoint, token_endpoint and scopes_supported.

Claim mappings are used to map OpenID Connect terms used by federated providers and clients to JSON-LD terms used in a Credential. The defined claims are also used for display purposes in a client, like a Mobile Wallet.

ZKP-enabled BBS+ credential: If you wish to offer a ZKP-enabled Verifiable Credential, the provided issuer DID must be a did:key with a key type of bls12381g2. The platform will automatically detect this capability and issue a ZKP-enabled BBS+ credential.

ZKP-enabled BBS+ credentials are an experimental feature and the implementation may change resulting in issued credentials becoming invalid.

Authorizations:
Request Body schema: application/json

The issuer payload

required
object

Credential information

required
object

Federated OIDC Provider details

required
Array of objects

Map OpenID Connect terms to JSON-LD terms

Responses

Request samples

Content type
application/json
{
  • "credential": {
    },
  • "federatedProvider": {
    },
  • "claimMappings": [
    ]
}

Response samples

Content type
application/json
{}

Retrieve list of OIDC Issuers

Returns a list of all OIDC Issuers in the Tenant.

Authorizations:
query Parameters
limit
number [ 1 .. 1000 ]

Range size of returned issuer entries, default 100

Example: limit=2
cursor
string

Starting point for the range of issuer entries

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

curl --request GET \
  --url https://tenant.vii.mattr.global/ext/oidc/v1/issuers \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",
  • "data": {}
}

Retrieve an OIDC Issuer

Retrieve an OIDC Issuer by providing an Issuer ID.

Authorizations:
path Parameters
id
required
string <uuid>

Issuer ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f

Responses

Request samples

curl --request GET \
  --url https://tenant.vii.mattr.global/ext/oidc/v1/issuers/983c0a86-204f-4431-9371-f5a22e506599 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{}

Update an OIDC Issuer

Update an OIDC Credential Issuer.

The issuerDid is the Issuer DID that will be used in the issued Credential.

The credentialName describes the Credential and credentialTypes defines the Credential Types for the issued Credential.

In order for the tenant to issue a new credential, the OIDC bridge will federate the authentication request to the OpenID Provider of the Issuer. The details of the Issuer OpenID Provider are provided in the federatedProviderUrl, federatedProviderScope, federatedProviderClientId and federatedProviderClientSecret attributes. If no federatedProviderScope is provided, the default value openid profile email will be used.

The /.well-known/openid-configuration endpoint of the federated provider needs to contain values for the authorization_endpoint, token_endpoint and scopes_supported which needs to contain openid and profile.

Claim mappings are used to map OpenID Connect terms used by federated providers and clients to JSON-LD terms used in a Credential. The jsonLdContext is used to define the JSON-LD schema for the JSON-LD terms. The defined claims are also used for display purposes in a client, like a Mobile Wallet.

ZKP-enabled BBS+ credential: If you wish to offer a ZKP-enabled Verifiable Credential, the provided issuer DID must be a did:key with a key type of bls12381g2. The platform will automatically detect this capability and issue a ZKP-enabled BBS+ credential.

ZKP-enabled BBS+ credentials are an experimental feature, credentials issued to the mobile wallet will not be validated at this time.

Authorizations:
path Parameters
id
required
string <uuid>

Issuer ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f
Request Body schema: application/json

Update an Issuer

required
object

Credential information

required
object

Federated OIDC Provider details

required
Array of objects

Map OpenID Connect terms to JSON-LD terms

Responses

Request samples

Content type
application/json
{
  • "credential": {
    },
  • "federatedProvider": {
    },
  • "claimMappings": [
    ]
}

Response samples

Content type
application/json
{}

Remove an OIDC Issuer

Removes an OIDC Issuer by providing an Issuer ID.

Authorizations:
path Parameters
id
required
string <uuid>

Issuer ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f

Responses

Request samples

curl --request DELETE \
  --url https://tenant.vii.mattr.global/ext/oidc/v1/issuers/983c0a86-204f-4431-9371-f5a22e506599 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "code": "BadRequest",
  • "message": "Validation Error",
  • "details": [
    ]
}

Create an OpenId credential offer payload

Create a payload that can form a message in the JWM format that can be used in sending notifications to subjects to start an OIDC Issuer credential offer flow.

  • Use a DID setup on the tenant as the from value, this should be a DID with a key type suitable for messaging (not a BLS key type)
  • Include a SubjectDID as the to value - this value is only used in the message construction, it should be the same value as the intended recipient.

To send a notification to the Subject DID holder, use the payload with the /messaging/encrypt and /messaging/send endpoints.

Authorizations:
path Parameters
id
required
string <uuid>

Issuer ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f
Request Body schema: application/json

Create a message payload for an Offer

from
required
string non-empty

DID on the tenant used in a message

to
required
Array of strings

List of SubjectDIDs

Responses

Request samples

Content type
application/json
{
  • "from": "did:key:z6MkreuqFq6WrwozTeGKuUDz8bniTFRNAg8f3ZB862YdLp7v",
  • "to": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "733d1de2-9286-447e-a701-29b1292089d0",
  • "to": [
    ],
  • "from": "did:key:z6MkreuqFq6WrwozTeGKuUDz8bniTFRNAg8f3ZB862YdLp7v",
  • "created_time": 1616052936783,
  • "body": {
    }
}

OIDC Issuer Client

Create a Client

Issuer clients are required to be created in the system for custom digital wallets and VC Issue flows that are enabled through the OIDC Credential Provider.

The Create Client endpoint accepts OpenID Connect standard registration parameters.

When dealing with personal identity information it is strongly recommended to follow the Authorization Code Flow which ensures sensitive data is transmitted via the /token endpoint back-channel.

Authorizations:
path Parameters
id
required
string <uuid>

Issuer ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f
Request Body schema: application/json

The client payload

name
required
string

Meaningful name for this Client

redirectUris
required
Array of strings <uri>

Redirection URI to which the response will be sent

responseTypes
Array of strings

Determines the authorization processing flow

grantTypes
Array of strings

OAuth Grant Type

tokenEndpointAuthMethod
string

OAuth Token Endpoint Authentication Method

idTokenSignedResponseAlg
string

Algorithm must match configured jwks, defaults to RS256

applicationType
string

Responses

Request samples

Content type
application/json
{
  • "name": "OIDC Client for Wallet",
  • "redirectUris": [],
  • "responseTypes": [
    ],
  • "grantTypes": [
    ],
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "idTokenSignedResponseAlg": "ES256",
  • "applicationType": "web"
}

Response samples

Content type
application/json
{
  • "id": "6a860559-21a3-4b57-9a2b-aaea3ba4683d",
  • "secret": "PiMkTfrEmPTKRFiPzjMFvYkYu.FwR.iZGFnC",
  • "name": "OIDC Client for Wallet",
  • "redirectUris": [],
  • "responseTypes": [
    ],
  • "grantTypes": [
    ],
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "idTokenSignedResponseAlg": "ES256",
  • "applicationType": "web"
}

Retrieve list of Clients

Returns a list of all OIDC Issuer Clients in the Tenant.

Authorizations:
path Parameters
id
required
string <uuid>

Issuer ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f
query Parameters
limit
number [ 1 .. 1000 ]

Range size of returned client entries, default 100

Example: limit=2
cursor
string

Starting point for the range of client entries

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

curl --request GET \
  --url https://tenant.vii.mattr.global/ext/oidc/v1/issuers/983c0a86-204f-4431-9371-f5a22e506599/clients \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",
  • "data": {
    }
}

Retrieve a Client

Retrieve an OIDC Issuer Client by providing a Client ID.

Authorizations:
path Parameters
id
required
string <uuid>

Issuer ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f
clientId
required
string <uuid>

Client ID

Example: 6a860559-21a3-4b57-9a2b-aaea3ba4683d

Responses

Request samples

curl --request GET \
  --url https://tenant.vii.mattr.global/ext/oidc/v1/issuers/983c0a86-204f-4431-9371-f5a22e506599/clients/6a860559-21a3-4b57-9a2b-aaea3ba4683d \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "id": "6a860559-21a3-4b57-9a2b-aaea3ba4683d",
  • "secret": "PiMkTfrEmPTKRFiPzjMFvYkYu.FwR.iZGFnC",
  • "name": "OIDC Client for Wallet",
  • "redirectUris": [],
  • "responseTypes": [
    ],
  • "grantTypes": [
    ],
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "idTokenSignedResponseAlg": "ES256",
  • "applicationType": "web"
}

Update a Client

Update an OIDC Issuer Client.

The Client endpoint accepts OpenID Connect standard registration parameters.

When dealing with personal identity information it is strongly recommended to follow the Authorization Code Flow which ensures sensitive data is transmitted via the /token endpoint back-channel.

Authorizations:
path Parameters
id
required
string <uuid>

Issuer ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f
clientId
required
string <uuid>

Client ID

Example: 6a860559-21a3-4b57-9a2b-aaea3ba4683d
Request Body schema: application/json

Update a client

name
required
string

Meaningful name for this Client

redirectUris
required
Array of strings <uri>

Redirection URI to which the response will be sent

responseTypes
Array of strings

Determines the authorization processing flow

grantTypes
Array of strings

OAuth Grant Type

tokenEndpointAuthMethod
string

OAuth Token Endpoint Authentication Method

idTokenSignedResponseAlg
string

Algorithm must match configured jwks, defaults to RS256

applicationType
string

Responses

Request samples

Content type
application/json
{
  • "name": "OIDC Client for Wallet",
  • "redirectUris": [],
  • "responseTypes": [
    ],
  • "grantTypes": [
    ],
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "idTokenSignedResponseAlg": "ES256",
  • "applicationType": "web"
}

Response samples

Content type
application/json
{
  • "id": "6a860559-21a3-4b57-9a2b-aaea3ba4683d",
  • "secret": "PiMkTfrEmPTKRFiPzjMFvYkYu.FwR.iZGFnC",
  • "name": "OIDC Client for Wallet",
  • "redirectUris": [],
  • "responseTypes": [
    ],
  • "grantTypes": [
    ],
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "idTokenSignedResponseAlg": "ES256",
  • "applicationType": "web"
}

Remove a Client

Removes an OIDC Issuer Client by providing a Client ID.

Authorizations:
path Parameters
id
required
string <uuid>

Issuer ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f
clientId
required
string <uuid>

Client ID

Example: 6a860559-21a3-4b57-9a2b-aaea3ba4683d

Responses

Request samples

curl --request DELETE \
  --url https://tenant.vii.mattr.global/ext/oidc/v1/issuers/983c0a86-204f-4431-9371-f5a22e506599/clients/6a860559-21a3-4b57-9a2b-aaea3ba4683d \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "code": "BadRequest",
  • "message": "Validation Error",
  • "details": [
    ]
}

OIDC Verifier Auth

Well Known OpenId Configuration

The standard OpenID Connect Well Known configuration metadata endpoint.

This endpoint is unprotected, public facing and can be used by any party wishing to discover the OpenID Connect capabilities.

path Parameters
id
required
string <uuid>

Verifier ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f

Responses

Request samples

curl --request GET \
  --url https://tenant.vii.mattr.global/ext/oidc/v1/verifiers/41458e5a-9092-40b7-9a26-d4eb43c5792f/.well-known/openid-configuration \
  --header 'Accept: application/json'

Response samples

Content type
application/json
{}

Retrieve Token

OIDC Token endpoint

The OpenId Connect /token endpoint is used to obtain the access_token and id_token by presenting a valid authorization code

path Parameters
id
required
string <uuid>

Verifier ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f
Request Body schema: application/x-www-form-urlencoded

Token endpoint request

One of
string
client_secret
string
grant_type
string
code
string
redirect_uri
string <uri>

Responses

Request samples

curl --request POST \
  --url https://tenant.vii.mattr.global/ext/oidc/v1/verifiers/41458e5a-9092-40b7-9a26-d4eb43c5792f/token \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'client_id=G1s1EPMml4L0zFd63drft' \
  --data 'client_secret=REPLACE_CLIENT_SECRET' \
  --data 'grant_type=authorization_code' \
  --data 'code=REPLACE_CODE' \
  --data 'redirect_uri=https://example.com'

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "bearer",
  • "refresh_token": "string",
  • "expires_in": 0,
  • "id_token": "string"
}

OIDC Verifiers

Create an OIDC Verifier

Create a new OIDC Credential Verifier for this tenant.

The verifierDid is the Verifier DID that will be used to securely send the Credential to.

The presentationTemplateId references the Presentation Template that defines what Credential is being requested for presentation.

Claim mappings are used to map JSON-LD terms used in a Credential to OpenID Connect terms used by clients.

Authorizations:
Request Body schema: application/json

The verifier payload

verifierDid
required
string

The Verifier DID

presentationTemplateId
required
string <uuid>

Presentation Template ID used to request certain credentials

required
Array of objects

Map OpenID Connect terms to JSON-LD terms

Responses

Request samples

Content type
application/json
{
  • "verifierDid": "did:key:z6MkrYVmyqSA93o4B1GwERM8kaQDMAUKAFV2TC3weQKeg9Gq",
  • "presentationTemplateId": "364b6a1b-3600-4927-a6ac-4d66aa6bbac3",
  • "claimMappings": []
}

Response samples

Content type
application/json
{
  • "id": "41458e5a-9092-40b7-9a26-d4eb43c5792f",
  • "verifierDid": "did:key:z6MkrYVmyqSA93o4B1GwERM8kaQDMAUKAFV2TC3weQKeg9Gq",
  • "presentationTemplateId": "364b6a1b-3600-4927-a6ac-4d66aa6bbac3",
  • "claimMappings": []
}

Retrieve list of OIDC Verifiers

Returns a list of all OIDC Verifiers in the Tenant.

Authorizations:
query Parameters
limit
number [ 1 .. 1000 ]

Range size of returned verifier entries, default 100

Example: limit=2
cursor
string

Starting point for the range of verifier entries

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

curl --request GET \
  --url https://tenant.vii.mattr.global/ext/oidc/v1/verifiers \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",
  • "data": {
    }
}

Retrieve an OIDC Verifier

Retrieve an OIDC Verifier by providing a Verifier ID.

Authorizations:
path Parameters
id
required
string <uuid>

Verifier ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f

Responses

Request samples

curl --request GET \
  --url https://tenant.vii.mattr.global/ext/oidc/v1/verifiers/41458e5a-9092-40b7-9a26-d4eb43c5792f \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "id": "41458e5a-9092-40b7-9a26-d4eb43c5792f",
  • "verifierDid": "did:key:z6MkrYVmyqSA93o4B1GwERM8kaQDMAUKAFV2TC3weQKeg9Gq",
  • "presentationTemplateId": "364b6a1b-3600-4927-a6ac-4d66aa6bbac3",
  • "claimMappings": []
}

Update an OIDC Verifier

Update an OIDC Credential Verifier.

The verifierDid is the Verifier DID that will be used to securely send the Credential to.

The presentationTemplateId references the Presentation Template that defines what Credential is being requested for presentation.

Claim mappings are used to map JSON-LD terms used in a Credential to OpenID Connect terms used by clients. The jsonLdContext is used to define the JSON-LD schema for the JSON-LD terms.

Authorizations:
path Parameters
id
required
string <uuid>

Verifier ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f
Request Body schema: application/json

Update a verifier

verifierDid
required
string

The Verifier DID

presentationTemplateId
required
string <uuid>

Presentation Template ID used to request certain credentials

required
Array of objects

Map OpenID Connect terms to JSON-LD terms

Responses

Request samples

Content type
application/json
{
  • "verifierDid": "did:key:z6MkrYVmyqSA93o4B1GwERM8kaQDMAUKAFV2TC3weQKeg9Gq",
  • "presentationTemplateId": "364b6a1b-3600-4927-a6ac-4d66aa6bbac3",
  • "claimMappings": []
}

Response samples

Content type
application/json
{
  • "id": "41458e5a-9092-40b7-9a26-d4eb43c5792f",
  • "verifierDid": "did:key:z6MkrYVmyqSA93o4B1GwERM8kaQDMAUKAFV2TC3weQKeg9Gq",
  • "presentationTemplateId": "364b6a1b-3600-4927-a6ac-4d66aa6bbac3",
  • "claimMappings": []
}

Remove an OIDC Verifier

Removes an OIDC Verifier by providing a Verifier ID.

Authorizations:
path Parameters
id
required
string <uuid>

Verifier ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f

Responses

Request samples

curl --request DELETE \
  --url https://tenant.vii.mattr.global/ext/oidc/v1/verifiers/41458e5a-9092-40b7-9a26-d4eb43c5792f \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "code": "BadRequest",
  • "message": "Validation Error",
  • "details": [
    ]
}

OIDC Verifier Client

Create a Client

Relying party clients are required to be created in the system for Authorization and VC Verify flows that are enabled through OIDC.

The Create Client endpoint accepts OpenID Connect standard registration parameters.

When dealing with personal identity information it is strongly recommended to follow the Authorization Code Flow which ensures sensitive data is transmitted via the /token endpoint back-channel.

Authorizations:
path Parameters
id
required
string <uuid>

Verifier ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f
Request Body schema: application/json

The client payload

name
required
string

Meaningful name for this Client

redirectUris
required
Array of strings <uri>

Redirection URI to which the response will be sent

responseTypes
Array of strings

Determines the authorization processing flow

grantTypes
Array of strings

OAuth Grant Type

tokenEndpointAuthMethod
string

OAuth Token Endpoint Authentication Method

idTokenSignedResponseAlg
string

Algorithm must match configured jwks, defaults to RS256

applicationType
string
logoUri
string <uri>

The logo to display above the QR code

Responses

Request samples

Content type
application/json
{
  • "name": "OIDC Client for the verifier",
  • "redirectUris": [],
  • "responseTypes": [
    ],
  • "grantTypes": [
    ],
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "idTokenSignedResponseAlg": "ES256",
  • "applicationType": "web",
}

Response samples

Content type
application/json
{
  • "id": "da9bb6e4-c9ae-4468-b6ac-72b90d6efd5d",
  • "secret": "H2epdcmNJ46hXJo5opdzvhbZK9W2ZGPkQh.E",
  • "name": "OIDC Client for the verifier",
  • "redirectUris": [],
  • "responseTypes": [
    ],
  • "grantTypes": [
    ],
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "idTokenSignedResponseAlg": "ES256",
  • "applicationType": "web",
}

Retrieve list of Clients

Returns a list of all OIDC Verifier Clients in the Tenant.

Authorizations:
path Parameters
id
required
string <uuid>

Verifier ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f
query Parameters
limit
number [ 1 .. 1000 ]

Range size of returned client entries, default 100

Example: limit=2
cursor
string

Starting point for the range of client entries

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

curl --request GET \
  --url https://tenant.vii.mattr.global/ext/oidc/v1/verifiers/41458e5a-9092-40b7-9a26-d4eb43c5792f/clients \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",
  • "data": {
    }
}

Retrieve a Client

Retrieve an OIDC Verifier Client by providing a Client ID.

Authorizations:
path Parameters
id
required
string <uuid>

Verifier ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f
clientId
required
string <uuid>

Client ID

Example: da9bb6e4-c9ae-4468-b6ac-72b90d6efd5d

Responses

Request samples

curl --request GET \
  --url https://tenant.vii.mattr.global/ext/oidc/v1/verifiers/41458e5a-9092-40b7-9a26-d4eb43c5792f/clients/da9bb6e4-c9ae-4468-b6ac-72b90d6efd5d \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "id": "da9bb6e4-c9ae-4468-b6ac-72b90d6efd5d",
  • "secret": "H2epdcmNJ46hXJo5opdzvhbZK9W2ZGPkQh.E",
  • "name": "OIDC Client for the verifier",
  • "redirectUris": [],
  • "responseTypes": [
    ],
  • "grantTypes": [
    ],
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "idTokenSignedResponseAlg": "ES256",
  • "applicationType": "web",
}

Update a Client

Update an OIDC Verifier Client.

The Client endpoint accepts OpenID Connect standard registration parameters.

When dealing with personal identity information it is strongly recommended to follow the Authorization Code Flow which ensures sensitive data is transmitted via the /token endpoint back-channel.

Authorizations:
path Parameters
id
required
string <uuid>

Verifier ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f
clientId
required
string <uuid>

Client ID

Example: da9bb6e4-c9ae-4468-b6ac-72b90d6efd5d
Request Body schema: application/json

Update a client

name
required
string

Meaningful name for this Client

redirectUris
required
Array of strings <uri>

Redirection URI to which the response will be sent

responseTypes
Array of strings

Determines the authorization processing flow

grantTypes
Array of strings

OAuth Grant Type

tokenEndpointAuthMethod
string

OAuth Token Endpoint Authentication Method

idTokenSignedResponseAlg
string

Algorithm must match configured jwks, defaults to RS256

applicationType
string
logoUri
string <uri>

The logo to display above the QR code

Responses

Request samples

Content type
application/json
{
  • "name": "OIDC Client for the verifier",
  • "redirectUris": [],
  • "responseTypes": [
    ],
  • "grantTypes": [
    ],
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "idTokenSignedResponseAlg": "ES256",
  • "applicationType": "web",
}

Response samples

Content type
application/json
{
  • "id": "da9bb6e4-c9ae-4468-b6ac-72b90d6efd5d",
  • "secret": "H2epdcmNJ46hXJo5opdzvhbZK9W2ZGPkQh.E",
  • "name": "OIDC Client for the verifier",
  • "redirectUris": [],
  • "responseTypes": [
    ],
  • "grantTypes": [
    ],
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "idTokenSignedResponseAlg": "ES256",
  • "applicationType": "web",
}

Remove a Client

Removes an OIDC Verifier Client by providing a Client ID.

Authorizations:
path Parameters
id
required
string <uuid>

Verifier ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f
clientId
required
string <uuid>

Client ID

Example: da9bb6e4-c9ae-4468-b6ac-72b90d6efd5d

Responses

Request samples

curl --request DELETE \
  --url https://tenant.vii.mattr.global/ext/oidc/v1/verifiers/41458e5a-9092-40b7-9a26-d4eb43c5792f/clients/da9bb6e4-c9ae-4468-b6ac-72b90d6efd5d \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REPLACE_ACCESS_TOKEN'

Response samples

Content type
application/json
{
  • "code": "BadRequest",
  • "message": "Validation Error",
  • "details": [
    ]
}