Migration from v1

v1 of TrustOS API is going to be deprecated and its use is not recommended. If you are using v1 of APIs, we recommend that you update to v2 as soon as possible.

This section is designed to facilitate the migration from v1 to v2. Below, we detail the most important changes that have been made in v2 of TrustOS, which may affect the migration of your systems.

Blockchain network

As part of the migration to v2, we have updated the core blockchain network within TrustOS. Previously, our systems were deployed by default on a private Hyperledger Fabric network. With v2, we have migrated to a private Hyperledger Besu network, based on the Ethereum Virtual Machine (EVM). This allows us to interact with any Ethereum-based network, expanding TrustOS capabilities and taking advantage of the latest implementations and improvements from the Ethereum community, such as ERC-4337 (Account Abstraction). Therefore, we recommend using this network for registering any asset or certificate within TrustOS. If you consult the available networks through the /providers endpoint, you will be able to see all the networks available to interact with TrustOS.

Please use the networkId 10004 (Telefónica Tech’s Hyperledger Besu). If you need to register on public networks, please contact us.

API Authentication

In order to achieve proper modularization of functionalities within TrustOS, we have removed the authentication endpoints from the certificates and traceability module. To interact with TrustOS APIs, it is necessary to authenticate previously in the identity module. To do this, you must use the /login endpoint to obtain an authentication token (jwt). This token must be included in the header of all requests to TrustOS APIs, under the name Authorization.

Data Persistence

The information stored in the lab environment, such as certificates and assets, as well as users, will be deleted and cannot be recovered. In the case of the production environment, since we have migrated to a new blockchain network, all data stored in the private Hyperledger Fabric network has been transferred within TrustOS systems, enabled only in read-only mode. That is, the information will still be accessible through the APIs, but write operations cannot be performed.

Identifiers

The identifiers for new users and certificates have been updated:

Users: User identifiers have changed from did:vtn:trustid:<userId> to did:user:<userId>.
Certificates: Certificate identifiers have changed from did:vtn:c1:certid:<certId> to did:<environment>:certid:<certId>.

New Formats

Response Format

In order to obtain more clarity in responses from TrustOS, we have updated the response format of TrustOS APIs. We have moved from the format:

{
    "output": "..."
}

to the format:

{
    "statusCode": 200,
    "message": "...",
    "data": "..."
}

Certificate Format

The certificate format has evolved, modifying and adding new fields and structures. Moving from:

{
  "output": {
    "certID": "did:vtn:channel1:certid:c3ff3f3c055ae9eb4884123f0627cd8a4496d8ad381766c963ae496a6cd4669f",
    "data": {
      "badge": {
        "name": "Certificate name",
        "description": "Certificate description",
        "type": "content",
        "content": [
          {}
        ]
      },
      "issuer": "did:vtn:trustid:afa1f9ad8e593ced39051d1f909b33b0852f18c16e89613bc7e3d2b5ef43a878",
      "issuedOn": "2025-12-31T23:59:59+00:00",
      "expires": "",
      "hash": "Bs2nFa30Ghu84uwBnjs2aOi53qe6r6YTpjk+o/HB2c="
    },
    "metadata": [
      {
        "type": "Creation/Signature/Revocation/Evidence",
        "verification": {},
        "signatures": {},
        "public_evidences": {},
        "revoked": false,
        "datetime": "1592568489",
        "hfTxId": "3ae1d6b0f914aee4ce7105ddd65c4cf2dcf160ca398297a13032aaf33b50ed291",
        "hash": "Ni7JYQG6GSmlEjWoRj2xrfF6ZVFhqBDPzyjk+o/HB2c="
      }
    ],
    "access": {}
  }
}

to the following format:

{
  "statusCode": 201,
  "message": "Certificate created",
  "data": {
    "certID": "did:<env>:certid:<id>",
    "data": {
      "name": "Certificate",
      "description": "Certificate description",
      "type": "content",
      "content": {
        "test": "value"
      },
      "issuer": "did:user:<id>",
      "issuedOn": 1712241156,
      "hash": "8b3479f4b67f32d0306b9d64c80d0f9612cac650480382be2b23d354d1e3f3e5"
    },
    "metadata": [
      {
        "type": "Evidence",
        "networkId": 1337,
        "smartContract": "0x23Eab6f0a86b5bC484209Ceed2E3091aF466b9dA",
        "transactionHash": "0x2f90d7295a5a5997792ff8f3680c1a237d64d188f358c0241e87dda2e3d21c39",
        "trustpointHash": "8b0d43f4b67f09d0306b9d64c80d0f9612cac650480382be2b23dfad41e3f3a5",
        "timestamp": 1712241156
      }
    ],
    "access": {
      "public": true,
      "externalId": "externalid"
    }
  }
}

Asset Format

Like the certificates module, the asset format has evolved, modifying and adding new fields and structures. Moving from:

{
  "output": {
    "assetId": "assetId-01",
    "data": {
      "name": "Asset 1",
      "description": "Description of asset 1",
      "type": "type1"
    },
    "isBatch": false,
    "transactions": [
      {
        "metadata": {
          "color": "blue",
          "position": {
            "x": "98.35",
            "y": "-12.32"
          }
        },
        "timestamp": 1676902956,
        "userOwner": "did:vtn:trustid:3c375221a72d34cff8222658f564d7fc466d238205117d862aea1c30e7560456",
        "hash": "ddE9OUf1U0OBohDQcGjvW2EueT427OCqL1bNLNewOws="
      },
      {
        "metadata": {
          "color": "red",
          "position": {
            "x": "98.35",
            "y": "-12.32"
          }
        },
        "timestamp": 1492568449,
        "userOwner": "did:vtn:trustid:3c375221a72d34cff8222658f564d7fc466d238205117d862aea1c30e7560456",
        "hash": "ddE9OUf1U0OBohDQc6jvW2EueT424OCqL1bNLNewOws="
      }
    ]
  }
}

to the following format:

{
  "statusCode": 200,
  "message": "2 transaction(s) found",
  "data": {
    "assetId": "asset0",
    "data": {
      "id": "A2839RP",
      "version": "1"
    },
    "networkId": 1337,
    "assetHash": "23b45015fec4449201e026535329d149725ffab4e8421b753f388d8e6ecb90ab",
    "transactions": [
      {
        "metadata": {
          "color": "green",
          "position": {
            "x": "93.35",
            "y": "-12.32"
          }
        },
        "timestamp": 1712219349,
        "userOwner": "did:user:<id>",
        "hash": "234f5a614417da701eeb8aae741efed2398128d94cfe71c4f65435fd26158123",
        "smartContract": "0x23Eab6f0a86b5bC484209Ceed2E3091aF466b9dA",
        "transactionHash": "0x32ccc8b56db88046e42d48a734c2db0343f21ad838ddd3f7bbdb49f75b4f645f"
      },
      {
        "metadata": {
          "delivered": true
        },
        "timestamp": 1712137368,
        "userOwner": "did:user:<id>",
        "hash": "234f5a614417da701eeb8aae741efed2398128d94cfe71c4f65435fd26158123",
        "smartContract": "0x23Eab6f0a86b5bC484209Ceed2E3091aF466b9dA",
        "transactionHash": "0x32ccc8b56db88046e42d48a734c2db0343f21ad838ddd3f7bbdb49f75b4f645f"
      }
    ]
  }
}

Other changes

The functionality to make a certificate private has been added
Token API is discontinued
The expiration time of the Login jwt, as well as the refresh token, have been updated.

If after reading this guide you still have questions, don’t hesitate to contact us.

General

More

Blockchain network

API Authentication

Data Persistence

Identifiers

New Formats

Response Format

Certificate Format

Asset Format

Other changes

​Blockchain network

​API Authentication

​Data Persistence

​Identifiers

​New Formats

​Response Format

​Certificate Format

​Asset Format

​Other changes

Blockchain network

API Authentication

Data Persistence

Identifiers

New Formats

Response Format

Certificate Format

Asset Format

Other changes