Platform Core API (v1.0.1)

Download OpenAPI specification:Download

NOTICE

This is not the latest version of our API Reference. Some of the endpoints have underwent changes that are not backwards compatible to what is described in this reference. Refer to the latest version of our API reference and to our API reference changelog to review changes.

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-url}/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 identified as requiring bearerAuth (this is required for the majority 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"

bearerAuthOpenIdCredentials

Security Scheme Type: HTTP
HTTP Authorization Scheme bearer

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
Request Body schema: application/json
client_id
required
string
client_secret
required
string
audience
required
string
grant_type
required
string
Responses
200

Successful response

401

Unauthorized

post/oauth/token
Request samples
application/json
{
  • "client_id": "htf792W4p4MedZbnoWAs51EfqUt4d2",
  • "client_secret": "d3fYDX7FjPg1D1h2viARXsolPByQ9vMfg8LHylBy8F4s5KJLB4HhHGOxxqJnSj3G",
  • "grant_type": "client_credentials"
}
Response samples
application/json
{
  • "access_token": "s2dgbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6s2dcaEROemRDf5gbRVEwTTVSVFE0TmtZME9UZzVNVEpDTlVJNFJqRTBPREExTmpZMk1qazFPQSJ9",
  • "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:

  • Organization Name
  • Domain Name
  • Logo

Returns

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

SecuritybearerAuth
Request
Request Body schema:
required

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

Responses
201

Custom domain created

400

Bad request, Invalid request body

post/core/v1/config/domain
Request samples
{}
Response samples
application/json
{
  • "name": "Site Worker Cert",
  • "domain": "ssi.sitesafe.org.nz",
  • "verificationToken": "SdsswaSADasdASdasdasdsa",
  • "isVerified": false,
  • "verifiedAt": null
}

Retrieve custom domain

Retrieve the custom domain information and it's verification status for your MATTR VII tenant.

SecuritybearerAuth
Responses
200

Custom domain returned

404

Not Found

get/core/v1/config/domain
Request samples
Response samples
application/json
{
  • "name": "Site Worker Cert",
  • "domain": "ssi.siteworkercert.com",
  • "verificationToken": "SdsswaSADasdASdasdasdsa",
  • "isVerified": false,
  • "verifiedAt": null
}

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.

SecuritybearerAuth
Responses
204

Custom domain deleted

404

Not Found

delete/core/v1/config/domain
Request samples
Response samples
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.

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

Responses
200

Custom Domain updated

404

Not Found

put/core/v1/config/domain
Request samples
application/json
{}
Response samples
application/json
{
  • "name": "Site Worker Cert",
  • "domain": "ssi.siteworkercert.com",
  • "verificationToken": "SdsswaSADasdASdasdasdsa",
  • "isVerified": true,
  • "verifiedAt": "2021-04-15T07:37:25.008Z"
}

Verify custom domain

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

SecuritybearerAuth
Responses
204

Custom domain verified

400

Bad Request

404

Not Found

post/core/v1/config/domain/verify
Request samples
Response samples
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 deterministically found at the root of the tenant subdomain or alias by any party wishing to discover the domain to DID relationship.

Responses
200

List of DID Configuration entries

get/.well-known/did-configuration
Request samples
Response samples
application/json
{
  • "entries": [
    ]
}

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

Options: The options parameter is used to define further configuration when creating the DID, the available options vary between methods.

Note: W3C DIDs are an emerging standard at the W3C, DIDs issued during a trial on the MATTR VII platform may be subject to change, as you move into production workloads please get in touch to discuss your needs.

Creating did:key

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

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 Key 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 by specifying the domain where the DID document is going to be hosted in the options body.

If the keyType in options is not provided, a DID will be created with Ed25519, Bls12381G2, and P-256 key types.

If the keyType in options is set to P-256, then this DID can only be used to create Compact Credentials, NOT Web Credentials.

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

A DID with a DID method of ion can be created.

Public DID Document is anchored by batching using the ION network, due to the lag incurred in registering the DID Document, which may take between 20-120 minutes, the registrationStatus will remain as PROCESSING until the DID Document can be retrieved from the public nodes.

Note: The creation of ION DIDs during a trial of the MATTR VII platform may be subject to change, as you move into production workloads please get in touch to discuss your needs.

Returns

The DID, associated metadata and registration status.

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

SecuritybearerAuth
Request
Request Body schema: application/json
required

Options for creating the decentralized identifier

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

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

Responses
201

DID document created

400

Bad request

post/core/v1/dids
Request samples
application/json
{
  • "method": "web",
  • "options": {
    }
}
Response samples
application/json
{
  • "did": "did:web:organization.com",
  • "registrationStatus": "COMPLETED",
  • "localMetadata": {
    }
}

Retrieve a list of DIDs

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

SecuritybearerAuth
Request
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
200

A list of DIDs

get/core/v1/dids
Request samples
Response samples
application/json
{
  • "data": [
    ],
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM"
}

Resolve a DID

When the DID is retrieved by the DID provided in the path, the DID Document is also attempted to be resolved by using the DID method and method identifier, this may involve a network call depending on the method involved.

Example:

did:key:z6Mkjr7vfzBfamiN6Wi6cyQUgTq6CEMXP1MzWQawsUEXJoa9 - the public key is encapsulated in the DID did:ion:EiBbvWpBHPql_2W9sObr4vPFl9k9InEDYOEDXvPPRDRyBg - will be resolved on the ION network did:web:mattr.global - will be resolved by accessing the /.well-known/did.json of the domain

Returns

If the DID Document is publicly resolvable it is returned along with meta-data already held about the DID by the tenant;

  • didDocument: See our tutorials on MATTR Learn to understand more about the anatomy of the DID Document for each method.
  • registrationStatus: Ledger-based DIDs may incur a lag in processing to the ledger. Also for DIDs that require additional actions (e.g. did:web) this status will be update from PROCESSING to COMPLETED once publicly resolvable.
  • localMetadata: This includes the initial DID document that the platform expects to find publicly resolvable.
SecuritybearerAuth
Request
path Parameters
id
required
string <did>

DID

Example: did:key:z6Mkjr7vfzBfamiN6Wi6cyQUgTq6CEMXP1MzWQawsUEXJoa9
Responses
200

A DID Document and meta-data

404

Not Found

get/core/v1/dids/{id}
Request samples
Response samples
application/json
{
  • "did": "did:web:organization.com",
  • "registrationStatus": "COMPLETED",
  • "localMetadata": {
    }
}

Delete a DID

Deletes a DID and all associated metadata including the Private keys from the platform and KMS. For ledger-based DIDs the public DID Document will still be available. For did:web you can remove the did.json from your hosted domain.

SecuritybearerAuth
Request
path Parameters
id
required
string <did>

DID

Example: did:key:z6Mkjr7vfzBfamiN6Wi6cyQUgTq6CEMXP1MzWQawsUEXJoa9
Responses
204

DID successfully deleted

400

Bad request

404

Not Found

delete/core/v1/dids/{id}
Request samples
Response samples
application/json
{
  • "code": "BadRequest",
  • "message": "Validation Error",
  • "details": [
    ]
}

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. Simply put, from your DID document, you can find it in DID.localMetadata.initialDidDocument.authentication[0]

{
    "did": "did:web:organization.com",
    "registrationStatus": "COMPLETED",
    "localMetadata": {
        "keys": [
            {
                "didDocumentKeyId": "did:web:organization.com#2vcj3MjR4d",
                "kmsKeyId": "a0cba537-ffe1-486d-aedd-6ead80e75519"
            },
            {
                "didDocumentKeyId": "did:web:organization.com#CU6dJt9p8t",
                "kmsKeyId": "250c4e1f-bae3-44ca-9f4e-4f7ff15851e2"
            }
        ],
        "registered": 1674421454614,
        "initialDidDocument": {
            "@context": [
                "https://w3.org/ns/did/v1",
                "https://w3id.org/security/suites/x25519-2019/v1",
                "https://w3id.org/security/suites/ed25519-2018/v1"
            ],
            "id": "did:web:organization.com",
            "verificationMethod": [
                {
                    "id": "did:web:organization.com#2vcj3MjR4d",
                    "controller": "did:web:organization.com",
                    "type": "Ed25519VerificationKey2018",
                    "publicKeyBase58": "2vcj3MjR4dSKq5asFQ9oor7iZsqTKTfBpjLHgaP15Y24"
                }
            ],
            "authentication": [                     
                "did:web:organization.com#2vcj3MjR4d"
            ],
            "assertionMethod": [
                "did:web:organization.com#2vcj3MjR4d"
            ],
            "capabilityDelegation": [
                "did:web:organization.com#2vcj3MjR4d"
            ],
            "capabilityInvocation": [
                "did:web:organization.com#2vcj3MjR4d"
            ],
            "keyAgreement": [
                {
                    "id": "did:web:organization.com#CU6dJt9p8t",
                    "controller": "did:web:organization.com",
                    "type": "X25519KeyAgreementKey2019",
                    "publicKeyBase58": "CU6dJt9p8twE4hmyGVFbVpUMmu6G732bVgD1tNupwYY7"
                }
            ]
        }
    }
}

Returns

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

SecuritybearerAuth
Request
Request Body schema: application/json
required

Sign message request

didUrl
required
string

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

payload
required
object (JSONObjectMessage)

A JSON Object plaintext message

Responses
200

Message signed

400

Error signing message

post/core/v1/messaging/sign
Request samples
application/json
{
  • "didUrl": "did:web:organization.com#2vcj3MjR4d",
  • "payload": {
    }
}
Response samples
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.

SecuritybearerAuth
Request
Request Body schema: application/json
required

JWS to verify

jws
string

Compact form of JWS

Responses
200

Verification has been performed, see response body for result

400

Invalid JWS

post/core/v1/messaging/verify
Request samples
application/json
{
  • "jws": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
Response samples
application/json
{
  • "payload": "payload",
  • "didUrl": "did:web:organization.com#2vcj3MjR4d",
  • "did": "did:web:organization.com",
  • "verified": true,
  • "signerPublicJwk": {
    }
}

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.

Simply put, you can find the value to use as senderDidUrl from DID.localMetadata.initialDidDocument.keyAgreement[0].id

{
    "did": "did:web:organization.com",
    "registrationStatus": "PROCESSING",
    "localMetadata": {
        "keys": [
            {
                "didDocumentKeyId": "did:web:organization.com#2vcj3MjR4d",
                "kmsKeyId": "a0cba537-ffe1-486d-aedd-6ead80e75519"
            },
            {
                "didDocumentKeyId": "did:web:organization.com#CU6dJt9p8t",
                "kmsKeyId": "250c4e1f-bae3-44ca-9f4e-4f7ff15851e2"
            }
        ],
        "registered": 1674421454614,
        "initialDidDocument": {
            "@context": [
                "https://w3.org/ns/did/v1",
                "https://w3id.org/security/suites/x25519-2019/v1",
                "https://w3id.org/security/suites/ed25519-2018/v1"
            ],
            "id": "did:web:organization.com",
            "verificationMethod": [
                {
                    "id": "did:web:organization.com#2vcj3MjR4d",
                    "controller": "did:web:organization.com",
                    "type": "Ed25519VerificationKey2018",
                    "publicKeyBase58": "2vcj3MjR4dSKq5asFQ9oor7iZsqTKTfBpjLHgaP15Y24"
                }
            ],
            "authentication": [
                "did:web:organization.com#2vcj3MjR4d"
            ],
            "assertionMethod": [
                "did:web:organization.com#2vcj3MjR4d"
            ],
            "capabilityDelegation": [
                "did:web:organization.com#2vcj3MjR4d"
            ],
            "capabilityInvocation": [
                "did:web:organization.com#2vcj3MjR4d"
            ],
            "keyAgreement": [
                {                        
                    "id": "did:web:organization.com#CU6dJt9p8t",
                    "controller": "did:web:organization.com",
                    "type": "X25519KeyAgreementKey2019",
                    "publicKeyBase58": "CU6dJt9p8twE4hmyGVFbVpUMmu6G732bVgD1tNupwYY7"
                }
            ]
        }
    }
}

Returns

SecuritybearerAuth
Request
Request Body schema: application/json
required

Encryption params

senderDidUrl
required
string
recipientDidUrls
required
Array of strings
payload
required
object
Responses
200

Message encrypted

400

Bad Request

post/core/v1/messaging/encrypt
Request samples
application/json
{
  • "senderDidUrl": "did:web:organization.com#CU6dJt9p8t",
  • "recipientDidUrls": [
    ],
  • "payload": {}
}
Response samples
application/json
{
  • "jwe": {
    }
}

Decrypt a message

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

The jwe attribute for request body can be extracted from the jwe attribute of the response body you get from POST core/v1/messaging/encrypt (Encrypt a message). You don't need to construct the value for jwe by yourself.

Alternatively, the jwe field also accepts a jwe string. You can obtain it by encoding your jwe object using Base64 encoding method.

You can obtain a JWE string (In Compact Serialisation format) by following the JWE open-standard: BASE64URL(UTF8(JWE Protected Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || ASE64URL(JWE Authentication Tag)

For reference, this is the open-standard for JWE Compact Serialisation.

SecuritybearerAuth
Request
Request Body schema: application/json
required

Decryption params

required
string or EncryptedMessage (object)
Responses
200

Message Decrypted

400

Bad Request

post/core/v1/messaging/decrypt
Request samples
application/json
{
  • "jwe": "eyJhbGciOiJFZERTQSIsImtpZCI6ImRpZDp3ZWI6bWF0dHIuZ2xvYmFsI0V5MkN2V2N5MzQifQ.eyJtZXNzYWdlIjoidGVzdCJ9.dMvOGkfbRrjUJL7XYYAp1UxoHlt8J0N5_vRRLpTEHtQ4s8lwnMd0lhg7HiZVfvEyzk54f6J0CgTV5oHzVscdAA"
}
Response samples
application/json
{
  • "payload": "string",
  • "senderDidUrl": "did:web:organization.com#2vcj3MjR4d",
  • "senderPublicJwk": { },
  • "recipientDidUrl": "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d"
}

Send a message

Send an encrypted 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.

SecuritybearerAuth
Request
Request Body schema: application/json
to
string

recipient DID

string or object

JWE message

Responses
200

Message sent

400

Error sending message

post/core/v1/messaging/send
Request samples
application/json
{
  • "to": "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d",
  • "message": {
    }
}
Response samples
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": [
    ]
}

Create an inbox

An inbox will hold messages for DIDs that are registered with the inbox

SecuritybearerAuth
Request
Request Body schema: application/json
required

Inbox configuration

name
required
string non-empty
Responses
201

Inbox Created

400

Bad request

post/core/v1/messaging/inboxes
Request samples
application/json
{
  • "name": "YOUR_INBOX"
}
Response samples
application/json
{
  • "id": "string",
  • "name": "string"
}

List inboxes

Returns a list of all registered inboxes for the tenant

SecuritybearerAuth
Request
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
200

A list of inboxes

get/core/v1/messaging/inboxes
Request samples
Response samples
application/json
{
  • "data": [
    ],
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM"
}

Retrieve an inbox

Returns a single inbox based on the Inbox ID

SecuritybearerAuth
Request
path Parameters
id
required
string

Inbox ID

Responses
200

Inbox configuration returned

400

Bad Request

404

Not Found

get/core/v1/messaging/inboxes/{id}
Request samples
Response samples
application/json
{
  • "id": "string",
  • "name": "string"
}

Update an inbox

Update the inbox configurations

SecuritybearerAuth
Request
path Parameters
id
required
string

Inbox ID

Request Body schema: application/json
required

Update Inbox configuration

name
required
string non-empty
Responses
200

Inbox updated

400

Bad Request

404

Not Found

put/core/v1/messaging/inboxes/{id}
Request samples
application/json
{
  • "name": "string"
}
Response samples
application/json
{
  • "id": "string",
  • "name": "string"
}

Delete an inbox

Deletes a specific inbox

SecuritybearerAuth
Request
path Parameters
id
required
string

Inbox ID

Responses
204

Inbox deleted

400

Bad Request

404

Not Found

delete/core/v1/messaging/inboxes/{id}
Request samples
Response samples
application/json
{
  • "code": "BadRequest",
  • "message": "Validation Error",
  • "details": [
    ]
}

Register DID with an inbox

This endpoint is responsible for registering DIDs to a specific Inbox. Currently, DID registration with inboxes is limited to did:key

SecuritybearerAuth
Request
path Parameters
id
required
string

Inbox ID

Request Body schema: application/json
required

DID registration information

did
required
string
jwt
string
Responses
201

DID registered with inbox

400

Bad Request

404

Not Found

post/core/v1/messaging/inboxes/{id}/dids
Request samples
application/json
{
  • "did": "string",
  • "jwt": "string"
}
Response samples
application/json
{
  • "did": "string"
}

List DIDs in an inbox

Returns a list of all DIDs for the specific Inbox

SecuritybearerAuth
Request
path Parameters
id
required
string

Inbox ID

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
200

A list of inbox DIDs

400

Bad Request

404

Not Found

get/core/v1/messaging/inboxes/{id}/dids
Request samples
Response samples
application/json
{
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",
  • "data": [
    ]
}

Unregister DID with an inbox

Unregister a DID from a specific inbox

SecuritybearerAuth
Request
path Parameters
id
required
string

Inbox ID

did
required
string

DID

Example: did:key:z6Mkjr7vfzBfamiN6Wi6cyQUgTq6CEMXP1MzWQawsUEXJoa9
Responses
204

DID unregistered from inbox

400

Bad Request

404

Not Found

delete/core/v1/messaging/inboxes/{id}/dids/{did}
Request samples
Response samples
application/json
{
  • "code": "BadRequest",
  • "message": "Validation Error",
  • "details": [
    ]
}

Retrieve messages from an inbox

Retrieving all the messages from an inbox

SecuritybearerAuth
Request
path Parameters
id
required
string

Inbox ID

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
200

A list of inbox messages

400

Bad Request

404

Not Found

get/core/v1/messaging/inboxes/{id}/messages
Request samples
Response samples
application/json
{
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",
  • "data": [
    ]
}

Retrieve a message

Returns an inbox message

SecuritybearerAuth
Request
path Parameters
id
required
string

Inbox ID

messageid
required
string

Message ID

Responses
200

An inbox message

400

Bad Request

404

Not Found

get/core/v1/messaging/inboxes/{id}/messages/{messageid}
Request samples
Response samples
application/json
{
  • "name": "string",
  • "createdAt": "2019-08-24",
  • "id": "string",
  • "inboxId": "string",
  • "payload": "string"
}

Delete a message from inbox

Deletes an inbox message

SecuritybearerAuth
Request
path Parameters
id
required
string

Inbox ID

messageid
required
string

Message ID

Responses
204

Message deleted

400

Bad Request

404

Not Found

delete/core/v1/messaging/inboxes/{id}/messages/{messageid}
Request samples
Response samples
application/json
{
  • "code": "BadRequest",
  • "message": "Validation Error",
  • "details": [
    ]
}

Webhooks

Create a webhook

Create a new webhook for this tenant.

The list of events are the names of the events that will trigger the request to the designated url.

The url entered is where the request will be sent.

Note: the URL has to have https:// as its prefix.

SecuritybearerAuth
Request
Request Body schema: application/json
required

The webhook payload

events
required
Array of strings

List of events that cause the webhook to fire

Items Value: "OidcIssuerCredentialIssued"
url
required
string <uri>

The destination url for the webhook

disabled
boolean

Whether or not the webhook is disabled

Responses
201

Webhook created

400

Bad Request

post/core/v1/webhooks
Request samples
application/json
{}
Response samples
application/json
{
  • "id": "0c099611-19c4-4f29-8724-6b9e5ba1ef7c",
  • "events": [
    ],
  • "disabled": false
}

Get a list of webhooks

Retrieve a list of webhooks for this tenant.

SecuritybearerAuth
Request
query Parameters
limit
number [ 1 .. 1000 ]

Range size of returned webhook entries, default 100

Example: limit=2
cursor
string

Starting point for the range of webhook entries

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h
Responses
200

Returns a page of webhooks

400

Bad Request

get/core/v1/webhooks
Request samples
Response samples
application/json
{
  • "data": [
    ],
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjItMDgtMjJUMDElM0E1OSUzQTE5LjYyMFomaWQ9MGMwOTk2MTEtMTljNC00ZjI5LTg3MjQtNmI5ZTViYTFlZjdj"
}

Get a webhook

Retrieve a specific webhook from this tenant.

SecuritybearerAuth
Request
path Parameters
id
required
string <uuid>

Webhook ID

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

Returns a webhook

400

Bad Request

get/core/v1/webhooks/{id}
Request samples
Response samples
application/json
{
  • "id": "0c099611-19c4-4f29-8724-6b9e5ba1ef7c",
  • "events": [
    ],
  • "disabled": false
}

Update a webhook

Update the following attributes on an existing webhook for this tenant.

events an array of events that will trigger the webhook to the designated url.

url for where the webhook will send the event payload.

disabled that specifies whether or not the webhook will listen for events.

SecuritybearerAuth
Request
path Parameters
id
required
string <uuid>

Webhook ID

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

Update a Webhook

events
required
Array of strings

List of events that cause the webhook to fire

Items Value: "OidcIssuerCredentialIssued"
url
required
string <uri>

The destination url for the webhook

disabled
boolean

Whether or not the webhook is disabled

Responses
200

Successfully updated the webhook

400

Bad Request

404

The webhook is not found

put/core/v1/webhooks/{id}
Request samples
application/json
{}
Response samples
application/json
{
  • "id": "0c099611-19c4-4f29-8724-6b9e5ba1ef7c",
  • "events": [
    ],
  • "disabled": false
}

Remove a webhook

Removes a specific webhook from this tenant.

SecuritybearerAuth
Request
path Parameters
id
required
string <uuid>

Webhook ID

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

Webhook deleted

400

Bad Request

404

The webhook is not found

delete/core/v1/webhooks/{id}
Request samples
Response samples
application/json
{
  • "code": "BadRequest",
  • "message": "Validation Error",
  • "details": [
    ]
}

Get a list of webhook JWKs

Retrieve a list of webhook JWKs for this tenant.

SecuritybearerAuth
Responses
200

Returns a page of webhook JWKs

get/core/v1/webhooks/jwks
Request samples
Response samples
application/json
{
  • "keys": [
    ]
}

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.

You can only create a Web Credential using a DID that's created using either Ed25519 or Bls12381G2 as their key type. If the your DID is created using keyType of P-256, then this DID can only be used to create Compact Credentials, NOT Web credentials.

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 (DID of the issuer) must be created using the key type of Bls12381G2. The platform will automatically detect this capability and issue a ZKP-enabled BBS credential. Note that the schema https://w3id.org/security/bbs/v2 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.

SecuritybearerAuth
Request
Request Body schema: application/json
required

The credential payload

name
string

This attribute is optional, however we strongly recommend providing a name to your credential

description
string

This attribute is optional, however we strongly recommend providing a description to your credential

@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. Note that VerifiableCredential must be included in the array

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), domain name and optional branding properties. Note that the Issuer id has to be a DID coming from the same tenant that you're using for executing this request (Create a Web Semantic Credential)

proofType
string

Proof type for the credential. Issuer DID must contain a key that supports the corresponding signing capability.

Enum: "Ed25519Signature2018" "BbsSignature2022"
object

Includes optional credential branding properties.

persist
boolean

Flag to indicate whether the full credential should be stored in platform. The credential will, by default, not be stored on our platform if this field is not provided.

revocable
boolean

Flag to indicate if the credential needs to support revocation. The credential created will be, by default, not revocable if this field is not provided.

expirationDate
string

Expiration date of the credential in an ISO 8601 date string format

Responses
201

Credential created

400

Bad request, Invalid request body

post/core/v1/credentials
Request samples
application/json
{}
Response samples
application/json
{}

Retrieve a list of credentials

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.

SecuritybearerAuth
Request
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
200

Returns a page of credentials

400

Bad query parameters in request.

get/core/v1/credentials
Request samples
Response samples
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.

SecuritybearerAuth
Request
path Parameters
id
required
string

Credential ID

Responses
200

Credential returned

400

Credential ID not in a UUID format

404

Not Found

get/core/v1/credentials/{id}
Request samples
Response samples
application/json
{}

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.

SecuritybearerAuth
Request
path Parameters
id
required
string

Credential ID

Responses
204

Credential deleted

400

Invalid id parameter format

404

Credential ID not found

delete/core/v1/credentials/{id}
Request samples
Response samples
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.
SecuritybearerAuth
Request
Request Body schema: application/json
object (VerifiableCredential)
Responses
200

Credential has been processed

post/core/v1/credentials/verify
Request samples
application/json
{}
Response samples
application/json
{
  • "verified": true
}

Revocation

Set credential revocation status

A credential can be revoked by setting the revocation status.

SecuritybearerAuth
Request
path Parameters
id
required
string <uuid>

Credential ID

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

Setting the revocation status

isRevoked
required
boolean

true if the credential is revoked, false otherwise

Responses
200

The revocation status has been set

404

Not Found

post/core/v1/credentials/{id}/revocation-status
Request samples