light-mode-image
Learn
API Reference

Participants

Create a Participant

Create participant

Creates a participant in the requested ecosystem.

Analytic events

  • ECOSYSTEM_PARTICIPANT_CREATE_START
  • ECOSYSTEM_PARTICIPANT_CREATE_SUCCESS
  • ECOSYSTEM_PARTICIPANT_CREATE_FAIL
POST/v1/ecosystems/{ecosystemId}/participants

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

Request Body

namestring

Name to easily identify the participant.

Length1 <= length <= 50
identifiersobject

Define the unique identifier that will be used by this participant to issue and/or verify credentials. Participants can have different identifiers for different credential formats. Each participant must have at least one defined credential format, and for each credential format a participant can define exactly one unique identifier.

  • Credentials are only valid in the ecosystem if they include an identifier of an issuer that is a participant in the ecosystem.
  • Verification requests are only valid in the ecosystem if they include an identifier of a verifier that is a participant in the ecosystem.
  • For mDocs this must be the PEM of a valid IACA used by this participant to sign mDocs, as defined in annex B of ISO/IEC 18013-5:2021. An exception to this aforementioned definition is that IACAs with a notBefore date in the future are considered valid.
isIssuer?boolean

Indicates whether the participant is an issuer in the ecosystem (true) or not (false). When set to false, the participant will not be able to issue any valid credential types, even if it is added to an issuer policy. The default value is false, as this assigns the least privileges to the new participant.

Defaultfalse
isVerifier?boolean

Indicates whether the created participant is a verifier in the ecosystem (true) or not (false). When set to false, the participant will not be able to verify any valid credential types, even if it is added to a verifier policy. The default value is false, as this assigns the least privileges to the new participant.

Defaultfalse
isIssuerConstrained?boolean

Indicates whether the created participant is constrained to only issue specific types of valid credentials (true) or not (false). When set to false, the issuer can issue all valid credential types defined within the ecosystem, even if it is added to a more limited issuer policy. The default value is true, as this assigns the least privileges to the new participant.

Defaulttrue
isVerifierConstrained?boolean

Indicates whether the created participant is constrained to only verify specific types of valid credentials (true) or not (false). When set to false, the verifier can verify all valid credential types defined within the ecosystem, even if it is added to a more limited verifier policy. The default value is true, as this assigns the least privileges to the new participant.

Defaulttrue
status?string

Indicates whether the participant is active or inactive. Only active participants are included in the ecosystem policy.

Default"Inactive"
Value in"Active" | "Inactive"
country?string

The country in which the participant is based. When provided, must be a valid Alpha 2 country code as per ISO 3166-1 and match the country value in the PEM certificate associated with the mobile identifier of this participant.

stateOrProvince?string

The state or province in which the participant is based, in ISO 3166-2 subdivision code format. When provided, must match the stateOrProvinceName value in the PEM certificate associated with the mobile identifier of this participant.

organizationAddress?string

The address of the organization that the participant represents.

organizationPhoneNumber?string

The phone number of the organization that the participant represents.

curl -X POST "https://example.vii.au01.mattr.global/v1/ecosystems/87880d7e-a4d0-462e-8383-3f1e5e16865d/participants" \  -H "Content-Type: application/json" \  -d '{    "name": "My Participant",    "identifiers": {}  }'
{
  "id": "a24e391a-c27f-4b6e-9805-1ee7e03f3c58",
  "ecosystemId": "87880d7e-a4d0-462e-8383-3f1e5e16865d",
  "name": "My Participant",
  "identifiers": {
    "web-semantic": "did:web:example.com",
    "compact-semantic": "did:web:example.com",
    "compact": "did:web:example.com",
    "mobile": [
      {
        "certificatePem": "-----BEGIN CERTIFICATE-----\r\nMIIBwzCCAWigAwIBAgIKRGC+CqoTGJKkkTAKBggqhkjOPQQDAjAgMR4wCQYDVQQG\r\nEwJOWjARBgNVBAMTCk1BVFRSIElBQ0EwHhcNMjMwODA4MDAwOTIxWhcNMzMwODA1\r\nMDAwOTIxWjAgMR4wCQYDVQQGEwJOWjARBgNVBAMTCk1BVFRSIElBQ0EwWTATBgcq\r\nhkjOPQIBBggqhkjOPQMBBwNCAASRu69fzdgM4odkyPtRcZd3eGWCw4BB7StZNGRm\r\nuIlrraUyv9SWPHgUYjYmRB1g7ERzj/pOSAspk71Y+QA+j9nPo4GJMIGGMBIGA1Ud\r\nEwEB/wQIMAYBAf8CAQMwDgYDVR0PAQH/BAQDAgAGMB0GA1UdDgQWBBSONcHGh4If\r\nO1dYorRpsuFrs+f8SDAcBgNVHRIEFTATgRFpbmZvQG1hdHRyLmdsb2JhbDAjBgNV\r\nHR8EHDAaMBiiFoYUaHR0cHM6Ly9tYXR0ci5nbG9iYWwwCgYIKoZIzj0EAwIDSQAw\r\nRgIhAPKJIGDSvp7VxRBLCWWeghqi8UUeO+dZsC49TUZcDMNxAiEAoh+7dT+l+GzX\r\nk0J2SoGmPiagrbAuIYyTHwzZZuYr1W4=\r\n-----END CERTIFICATE-----\r\n",
        "status": "Active",
        "docTypes": [
          "org.iso.18013.5.1"
        ]
      }
    ]
  },
  "isIssuer": false,
  "isVerifier": false,
  "isIssuerConstrained": true,
  "isVerifierConstrained": true,
  "status": "Active",
  "country": "US",
  "stateOrProvince": "US-AL",
  "organizationAddress": "1234 Main St, City, State, 12345",
  "organizationPhoneNumber": "012-3456789"
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}
Empty

Retrieve all Participants

Retrieve participants

Retrieves a list of participants from the requested ecosystem.

Analytic events

  • ECOSYSTEM_PARTICIPANT_RETRIEVE_LIST_START
  • ECOSYSTEM_PARTICIPANT_RETRIEVE_LIST_SUCCESS
  • ECOSYSTEM_PARTICIPANT_RETRIEVE_LIST_FAIL
GET/v1/ecosystems/{ecosystemId}/participants

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

ecosystemIdstring

The UUID of the ecosystem

Formatuuid

Query Parameters

limit?number

Range size of returned list.

Default100
Range1 <= value <= 1000
cursor?string

Starting point for the list of entries.

curl -X GET "https://example.vii.au01.mattr.global/v1/ecosystems/87880d7e-a4d0-462e-8383-3f1e5e16865d/participants?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h"
{
  "data": [
    {
      "id": "a24e391a-c27f-4b6e-9805-1ee7e03f3c58",
      "ecosystemId": "87880d7e-a4d0-462e-8383-3f1e5e16865d",
      "name": "My Participant",
      "identifiers": {
        "web-semantic": "did:web:example.com",
        "compact-semantic": "did:web:example.com",
        "compact": "did:web:example.com",
        "mobile": [
          {
            "certificatePem": "-----BEGIN CERTIFICATE-----\r\nMIIBwzCCAWigAwIBAgIKRGC+CqoTGJKkkTAKBggqhkjOPQQDAjAgMR4wCQYDVQQG\r\nEwJOWjARBgNVBAMTCk1BVFRSIElBQ0EwHhcNMjMwODA4MDAwOTIxWhcNMzMwODA1\r\nMDAwOTIxWjAgMR4wCQYDVQQGEwJOWjARBgNVBAMTCk1BVFRSIElBQ0EwWTATBgcq\r\nhkjOPQIBBggqhkjOPQMBBwNCAASRu69fzdgM4odkyPtRcZd3eGWCw4BB7StZNGRm\r\nuIlrraUyv9SWPHgUYjYmRB1g7ERzj/pOSAspk71Y+QA+j9nPo4GJMIGGMBIGA1Ud\r\nEwEB/wQIMAYBAf8CAQMwDgYDVR0PAQH/BAQDAgAGMB0GA1UdDgQWBBSONcHGh4If\r\nO1dYorRpsuFrs+f8SDAcBgNVHRIEFTATgRFpbmZvQG1hdHRyLmdsb2JhbDAjBgNV\r\nHR8EHDAaMBiiFoYUaHR0cHM6Ly9tYXR0ci5nbG9iYWwwCgYIKoZIzj0EAwIDSQAw\r\nRgIhAPKJIGDSvp7VxRBLCWWeghqi8UUeO+dZsC49TUZcDMNxAiEAoh+7dT+l+GzX\r\nk0J2SoGmPiagrbAuIYyTHwzZZuYr1W4=\r\n-----END CERTIFICATE-----\r\n",
            "status": "Active",
            "docTypes": [
              "org.iso.18013.5.1"
            ]
          }
        ]
      },
      "isIssuer": false,
      "isVerifier": false,
      "isIssuerConstrained": true,
      "isVerifierConstrained": true,
      "status": "Active",
      "country": "US",
      "stateOrProvince": "US-AL",
      "organizationAddress": "1234 Main St, City, State, 12345",
      "organizationPhoneNumber": "012-3456789"
    }
  ],
  "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM"
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}

Retrieve a Participant

Retrieve participant

Retrieves a participant from the requested ecosystem by its ID.

Analytic events

  • ECOSYSTEM_PARTICIPANT_RETRIEVE_START
  • ECOSYSTEM_PARTICIPANT_RETRIEVE_SUCCESS
  • ECOSYSTEM_PARTICIPANT_RETRIEVE_FAIL
GET/v1/ecosystems/{ecosystemId}/participants/{participantId}

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

ecosystemIdstring

The UUID of the ecosystem

Formatuuid
participantIdstring

The UUID of the participant

Formatuuid
curl -X GET "https://example.vii.au01.mattr.global/v1/ecosystems/87880d7e-a4d0-462e-8383-3f1e5e16865d/participants/a24e391a-c27f-4b6e-9805-1ee7e03f3c58"
{
  "id": "a24e391a-c27f-4b6e-9805-1ee7e03f3c58",
  "ecosystemId": "87880d7e-a4d0-462e-8383-3f1e5e16865d",
  "name": "My Participant",
  "identifiers": {
    "web-semantic": "did:web:example.com",
    "compact-semantic": "did:web:example.com",
    "compact": "did:web:example.com",
    "mobile": [
      {
        "certificatePem": "-----BEGIN CERTIFICATE-----\r\nMIIBwzCCAWigAwIBAgIKRGC+CqoTGJKkkTAKBggqhkjOPQQDAjAgMR4wCQYDVQQG\r\nEwJOWjARBgNVBAMTCk1BVFRSIElBQ0EwHhcNMjMwODA4MDAwOTIxWhcNMzMwODA1\r\nMDAwOTIxWjAgMR4wCQYDVQQGEwJOWjARBgNVBAMTCk1BVFRSIElBQ0EwWTATBgcq\r\nhkjOPQIBBggqhkjOPQMBBwNCAASRu69fzdgM4odkyPtRcZd3eGWCw4BB7StZNGRm\r\nuIlrraUyv9SWPHgUYjYmRB1g7ERzj/pOSAspk71Y+QA+j9nPo4GJMIGGMBIGA1Ud\r\nEwEB/wQIMAYBAf8CAQMwDgYDVR0PAQH/BAQDAgAGMB0GA1UdDgQWBBSONcHGh4If\r\nO1dYorRpsuFrs+f8SDAcBgNVHRIEFTATgRFpbmZvQG1hdHRyLmdsb2JhbDAjBgNV\r\nHR8EHDAaMBiiFoYUaHR0cHM6Ly9tYXR0ci5nbG9iYWwwCgYIKoZIzj0EAwIDSQAw\r\nRgIhAPKJIGDSvp7VxRBLCWWeghqi8UUeO+dZsC49TUZcDMNxAiEAoh+7dT+l+GzX\r\nk0J2SoGmPiagrbAuIYyTHwzZZuYr1W4=\r\n-----END CERTIFICATE-----\r\n",
        "status": "Active",
        "docTypes": [
          "org.iso.18013.5.1"
        ]
      }
    ]
  },
  "isIssuer": false,
  "isVerifier": false,
  "isIssuerConstrained": true,
  "isVerifierConstrained": true,
  "status": "Active",
  "country": "US",
  "stateOrProvince": "US-AL",
  "organizationAddress": "1234 Main St, City, State, 12345",
  "organizationPhoneNumber": "012-3456789"
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}

Update a Participant

Update participant

Updates a participant in the requested ecosystem by its ID.

Analytic events

  • ECOSYSTEM_PARTICIPANT_UPDATE_START
  • ECOSYSTEM_PARTICIPANT_UPDATE_SUCCESS
  • ECOSYSTEM_PARTICIPANT_UPDATE_FAIL
PUT/v1/ecosystems/{ecosystemId}/participants/{participantId}

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

Request Body

namestring

Name to easily identify the participant.

Length1 <= length <= 50
identifiersobject

Define the unique identifier that will be used by this participant to issue and/or verify credentials. Participants can have different identifiers for different credential formats. Each participant must have at least one defined credential format, and for each credential format a participant can define exactly one unique identifier.

  • Credentials are only valid in the ecosystem if they include an identifier of an issuer that is a participant in the ecosystem.
  • Verification requests are only valid in the ecosystem if they include an identifier of a verifier that is a participant in the ecosystem.
  • For mDocs this must be the PEM of a valid IACA used by this participant to sign mDocs, as defined in annex B of ISO/IEC 18013-5:2021. An exception to this aforementioned definition is that IACAs with a notBefore date in the future are considered valid.
isIssuer?boolean

Indicates whether the participant is an issuer in the ecosystem (true) or not (false). When set to false, the participant will not be able to issue any valid credential types, even if it is added to an issuer policy. The default value is false, as this assigns the least privileges to the new participant.

Defaultfalse
isVerifier?boolean

Indicates whether the created participant is a verifier in the ecosystem (true) or not (false). When set to false, the participant will not be able to verify any valid credential types, even if it is added to a verifier policy. The default value is false, as this assigns the least privileges to the new participant.

Defaultfalse
isIssuerConstrained?boolean

Indicates whether the created participant is constrained to only issue specific types of valid credentials (true) or not (false). When set to false, the issuer can issue all valid credential types defined within the ecosystem, even if it is added to a more limited issuer policy. The default value is true, as this assigns the least privileges to the new participant.

Defaulttrue
isVerifierConstrained?boolean

Indicates whether the created participant is constrained to only verify specific types of valid credentials (true) or not (false). When set to false, the verifier can verify all valid credential types defined within the ecosystem, even if it is added to a more limited verifier policy. The default value is true, as this assigns the least privileges to the new participant.

Defaulttrue
status?string

Indicates whether the participant is active or inactive. Only active participants are included in the ecosystem policy.

Default"Inactive"
Value in"Active" | "Inactive"
country?string

The country in which the participant is based. When provided, must be a valid Alpha 2 country code as per ISO 3166-1 and match the country value in the PEM certificate associated with the mobile identifier of this participant.

stateOrProvince?string

The state or province in which the participant is based, in ISO 3166-2 subdivision code format. When provided, must match the stateOrProvinceName value in the PEM certificate associated with the mobile identifier of this participant.

organizationAddress?string

The address of the organization that the participant represents.

organizationPhoneNumber?string

The phone number of the organization that the participant represents.

curl -X PUT "https://example.vii.au01.mattr.global/v1/ecosystems/87880d7e-a4d0-462e-8383-3f1e5e16865d/participants/a24e391a-c27f-4b6e-9805-1ee7e03f3c58" \  -H "Content-Type: application/json" \  -d '{    "name": "My Participant",    "identifiers": {}  }'
{
  "id": "a24e391a-c27f-4b6e-9805-1ee7e03f3c58",
  "ecosystemId": "87880d7e-a4d0-462e-8383-3f1e5e16865d",
  "name": "My Participant",
  "identifiers": {
    "web-semantic": "did:web:example.com",
    "compact-semantic": "did:web:example.com",
    "compact": "did:web:example.com",
    "mobile": [
      {
        "certificatePem": "-----BEGIN CERTIFICATE-----\r\nMIIBwzCCAWigAwIBAgIKRGC+CqoTGJKkkTAKBggqhkjOPQQDAjAgMR4wCQYDVQQG\r\nEwJOWjARBgNVBAMTCk1BVFRSIElBQ0EwHhcNMjMwODA4MDAwOTIxWhcNMzMwODA1\r\nMDAwOTIxWjAgMR4wCQYDVQQGEwJOWjARBgNVBAMTCk1BVFRSIElBQ0EwWTATBgcq\r\nhkjOPQIBBggqhkjOPQMBBwNCAASRu69fzdgM4odkyPtRcZd3eGWCw4BB7StZNGRm\r\nuIlrraUyv9SWPHgUYjYmRB1g7ERzj/pOSAspk71Y+QA+j9nPo4GJMIGGMBIGA1Ud\r\nEwEB/wQIMAYBAf8CAQMwDgYDVR0PAQH/BAQDAgAGMB0GA1UdDgQWBBSONcHGh4If\r\nO1dYorRpsuFrs+f8SDAcBgNVHRIEFTATgRFpbmZvQG1hdHRyLmdsb2JhbDAjBgNV\r\nHR8EHDAaMBiiFoYUaHR0cHM6Ly9tYXR0ci5nbG9iYWwwCgYIKoZIzj0EAwIDSQAw\r\nRgIhAPKJIGDSvp7VxRBLCWWeghqi8UUeO+dZsC49TUZcDMNxAiEAoh+7dT+l+GzX\r\nk0J2SoGmPiagrbAuIYyTHwzZZuYr1W4=\r\n-----END CERTIFICATE-----\r\n",
        "status": "Active",
        "docTypes": [
          "org.iso.18013.5.1"
        ]
      }
    ]
  },
  "isIssuer": false,
  "isVerifier": false,
  "isIssuerConstrained": true,
  "isVerifierConstrained": true,
  "status": "Active",
  "country": "US",
  "stateOrProvince": "US-AL",
  "organizationAddress": "1234 Main St, City, State, 12345",
  "organizationPhoneNumber": "012-3456789"
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}
Empty

Delete a Participant

Delete participant

Deletes a participant in the requested ecosystem by its ID.

Analytic events

  • ECOSYSTEM_PARTICIPANT_DELETE_START
  • ECOSYSTEM_PARTICIPANT_DELETE_SUCCESS
  • ECOSYSTEM_PARTICIPANT_DELETE_FAIL
DELETE/v1/ecosystems/{ecosystemId}/participants/{participantId}

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

curl -X DELETE "https://example.vii.au01.mattr.global/v1/ecosystems/87880d7e-a4d0-462e-8383-3f1e5e16865d/participants/a24e391a-c27f-4b6e-9805-1ee7e03f3c58"
Empty
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}

How would you rate this page?

Ecosystems

Previous Page

Credential types

Next Page

On this page

Create a ParticipantRetrieve all ParticipantsRetrieve a ParticipantUpdate a ParticipantDelete a Participant