light-mode-image
Learn
VICALAPI Reference

Signers

Create a VICAL signer

Create a VICAL signer

Creates a VICAL signer.

  • Only available in implementations using unmanaged (external) DTS root CA certificates.
  • A maximum of five VICAL signers can be created per tenant.

Analytic events

  • ECOSYSTEM_VICAL_SIGNER_CERTIFICATE_CREATE_START
  • ECOSYSTEM_VICAL_SIGNER_CERTIFICATE_CREATE_SUCCESS
  • ECOSYSTEM_VICAL_SIGNER_CERTIFICATE_CREATE_FAIL
POST/v1/ecosystems/certificates/vical-signers
AuthorizationBearer <token>

In: header

caIdstring

Internal identifier of the DTS root CA certificate that will be used for signing the VICAL signer.

  • Must be an unmanaged (external) DTS root CA certificate.
Formatuuid
curl -X POST "https://example.vii.au01.mattr.global/v1/ecosystems/certificates/vical-signers" \  -H "Content-Type: application/json" \  -d '{    "caId": "b0aae560-10e7-4247-8e96-7cdd3578a1e2"  }'
{
  "id": "782f1885-c7c2-4459-8426-b6d7c111b0b1",
  "csrPem": "-----BEGIN CERTIFICATE REQUEST-----\nMIIDXTCCAkWgAwIBAgIJAL5...\n-----END CERTIFICATE REQUEST-----",
  "caId": "b0aae560-10e7-4247-8e96-7cdd3578a1e2",
  "active": false
}
{
  "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"
    }
  ]
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}

Retrieve all VICAL signers

Retrieve all VICAL signers

Retrieves all VICAL signers.

Analytic events

  • ECOSYSTEM_VICAL_SIGNER_CERTIFICATE_RETRIEVE_LIST_START
  • ECOSYSTEM_VICAL_SIGNER_CERTIFICATE_RETRIEVE_LIST_SUCCESS
  • ECOSYSTEM_VICAL_SIGNER_CERTIFICATE_RETRIEVE_LIST_FAIL
GET/v1/ecosystems/certificates/vical-signers
AuthorizationBearer <token>

In: header

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/certificates/vical-signers?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h"
{
  "data": [
    {
      "id": "782f1885-c7c2-4459-8426-b6d7c111b0b1",
      "active": true,
      "certificatePem": "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIJAL5...\n-----END CERTIFICATE-----",
      "certificateFingerprint": "f6cad6e579d70b3973efa60624af731a580d1a11a7579e70f2f10f059dc86172",
      "certificateData": {
        "commonName": "example.com",
        "country": "US",
        "notAfter": "2024-10-22T00:00:00Z",
        "notBefore": "2023-10-22T00:00:00Z"
      }
    }
  ],
  "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 VICAL signer

Retrieve a VICAL signer

Retrieves a VICAL signer.

Analytic events

  • ECOSYSTEM_VICAL_SIGNER_CERTIFICATE_RETRIEVE_START
  • ECOSYSTEM_VICAL_SIGNER_CERTIFICATE_RETRIEVE_SUCCESS
  • ECOSYSTEM_VICAL_SIGNER_CERTIFICATE_RETRIEVE_FAIL
GET/v1/ecosystems/certificates/vical-signers/{vicalSignerId}
AuthorizationBearer <token>

In: header

Path Parameters

vicalSignerIdstring

Unique identifier of the VICAL signer.

Formatuuid
curl -X GET "https://example.vii.au01.mattr.global/v1/ecosystems/certificates/vical-signers/123e4567-e89b-12d3-a456-426614174000"
{
  "id": "782f1885-c7c2-4459-8426-b6d7c111b0b1",
  "active": true,
  "certificatePem": "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIJAL5...\n-----END CERTIFICATE-----",
  "certificateFingerprint": "f6cad6e579d70b3973efa60624af731a580d1a11a7579e70f2f10f059dc86172",
  "certificateData": {
    "commonName": "example.com",
    "country": "US",
    "notAfter": "2024-10-22T00:00:00Z",
    "notBefore": "2023-10-22T00:00:00Z"
  }
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}

Update a VICAL signer

Update a VICAL signer

Updates a VICAL signer by:

  • Providing a VICAL Signer Certificate (VSC) in PEM format that matches its Certificate Signing Request (CSR).
  • Activating or deactivating the VICAL signer. Only VICAL signers with a valid PEM certificate can be activated.
  • The certificatePem field becomes immutable after it's updated for the first time.

ℹ️ Note: Only available in implementations using unmanaged (external) DTS root CA certificates.

Analytic events

  • ECOSYSTEM_VICAL_SIGNER_CERTIFICATE_UPDATE_START
  • ECOSYSTEM_VICAL_SIGNER_CERTIFICATE_UPDATE_SUCCESS
  • ECOSYSTEM_VICAL_SIGNER_CERTIFICATE_UPDATE_FAIL
PUT/v1/ecosystems/certificates/vical-signers/{vicalSignerId}
AuthorizationBearer <token>

In: header

Path Parameters

vicalSignerIdstring

Unique identifier of the VICAL signer.

Formatuuid
active?boolean

Indicates if the VICAL signer is active. Only active VICAL signers can be used to sign VICALs.

certificatePem?string

VICAL Signer Certificate (VSC) in PEM format.

curl -X PUT "https://example.vii.au01.mattr.global/v1/ecosystems/certificates/vical-signers/123e4567-e89b-12d3-a456-426614174000" \  -H "Content-Type: application/json" \  -d '{}'
{
  "id": "782f1885-c7c2-4459-8426-b6d7c111b0b1",
  "active": true,
  "certificatePem": "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIJAL5...\n-----END CERTIFICATE-----",
  "certificateFingerprint": "f6cad6e579d70b3973efa60624af731a580d1a11a7579e70f2f10f059dc86172",
  "certificateData": {
    "commonName": "example.com",
    "country": "US",
    "notAfter": "2024-10-22T00:00:00Z",
    "notBefore": "2023-10-22T00:00:00Z"
  }
}
{
  "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"
    }
  ]
}

Delete a VICAL signer

Delete a VICAL signer

Deletes a VICAL signer.

ℹ️ Note: Only available in implementations using unmanaged (external) DTS root CA certificates.

Analytic events

  • ECOSYSTEM_VICAL_SIGNER_CERTIFICATE_DELETE_START
  • ECOSYSTEM_VICAL_SIGNER_CERTIFICATE_DELETE_SUCCESS
  • ECOSYSTEM_VICAL_SIGNER_CERTIFICATE_DELETE_FAIL
DELETE/v1/ecosystems/certificates/vical-signers/{vicalSignerId}
AuthorizationBearer <token>

In: header

Path Parameters

vicalSignerIdstring

Unique identifier of the VICAL signer.

Formatuuid
curl -X DELETE "https://example.vii.au01.mattr.global/v1/ecosystems/certificates/vical-signers/123e4567-e89b-12d3-a456-426614174000"
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?