MATTR Learn

Create a Participant

POST/v1/ecosystems/{ecosystemId}/participants

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

ecosystemId*string

The UUID of the ecosystem

Formatuuid

Request Body

application/json

name*string

Name to easily identify the participant.

Length1 <= length <= 50

identifiers*

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.

Response Body

`application/json`

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

GET/v1/ecosystems/{ecosystemId}/participants

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

ecosystemId*string

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.

Response Body

`application/json`

curl -X GET "https://example.vii.au01.mattr.global/v1/ecosystems/87880d7e-a4d0-462e-8383-3f1e5e16865d/participants"

{
  "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

GET/v1/ecosystems/{ecosystemId}/participants/{participantId}

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

ecosystemId*string

The UUID of the ecosystem

Formatuuid

participantId*string

The UUID of the participant

Formatuuid

Response Body

`application/json`

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

PUT/v1/ecosystems/{ecosystemId}/participants/{participantId}

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

ecosystemId*string

The UUID of the ecosystem

Formatuuid

participantId*string

The UUID of the participant

Formatuuid

Request Body

application/json

name*string

Name to easily identify the participant.

Length1 <= length <= 50

identifiers*

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

Defaultfalse

isVerifier?boolean

Defaultfalse

isIssuerConstrained?boolean

Defaulttrue

isVerifierConstrained?boolean

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

stateOrProvince?string

organizationAddress?string

The address of the organization that the participant represents.

organizationPhoneNumber?string

The phone number of the organization that the participant represents.

Response Body

`application/json`

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/v1/ecosystems/{ecosystemId}/participants/{participantId}

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

ecosystemId*string

The UUID of the ecosystem

Formatuuid

participantId*string

The UUID of the participant

Formatuuid

Response Body

`application/json`

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"
    }
  ]
}

Participants

201application/json

400application/json

404application/json

500

200application/json

400application/json

404application/json

200application/json

400application/json

404application/json

200application/json

400application/json

404application/json

500

204

400application/json

404application/json

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`