TIR JSON-RPC API

All methods are invoked via POST /trusted-issuers-registry/v1/jsonrpc with the header x-api-key: <API_KEY>.

---

Data types

IssuerType

The issuerType field accepts the following string values (not the numeric values):

Name	Numeric value	Description
NONE	0	No role assigned. Not used directly in publications.
ROOT_TAO	1	Root Trusted Accreditation Organisation. Only ISBE can use it.
TAO	2	Trusted Accreditation Organisation.
TI	3	Trusted Issuer.
REVOKED	4	Revoked accreditation. Use to revoke an existing attribute.

Ethereum address (address)

Hexadecimal string with 0x prefix and 40 characters: 0x8445fC96e27ceB0d1794be16a1Ac8BF5D765AACB.

Hexadecimal string (hexstring)

String with 0x prefix followed by hexadecimal characters: 0x3f4143c6f3a1c79b....

DID

String with the prefix did:isbe:uc: or did:isbe:uc-pre: depending on the environment, followed by the DID identifier.

---

setAttributeMetadata

Builds an unsigned transaction that registers the role metadata of an issuer in the TIR contract. The resulting transaction must be signed by the owner of the key associated with the from field and sent with sendSignedTransaction.

Request

{
  "jsonrpc": "2.0",
  "method": "setAttributeMetadata",
  "params": [
    {
      "from": "0x8445fC96e27ceB0d1794be16a1Ac8BF5D765AACB",
      "did": "did:isbe:uc:zpxbBfHYA5GN45rS1tSEBJg",
      "revisionId": "0x3f4143c6f3a1c79bb32f45a6cbd90ee6bb2e2e71eadda99e371a4a144c53050f",
      "issuerType": "TI",
      "taoDid": "did:isbe:uc:zj4sk7oEMx1SGNAzibWxVAV",
      "attributeIdTao": "0xbd6123874c340eaea25a1fc01785593c350fd9216ed3a69864549f8013d501b4"
    }
  ],
  "id": 1
}

Parameters

Field	Type	Mandatory	Description
from	address	✅	Ethereum address of who signs the transaction.
did	did	✅	DID of the subject to which the role is assigned.
revisionId	hexstring	✅	Attribute identifier in the TIR. Must match the reservedAttributeId of the accreditation. 64 hex chars + 0x prefix.
issuerType	IssuerType	✅	Role to register: ROOT_TAO, TAO, TI, or REVOKED.
taoDid	did	✅	DID of the TAO (or RTAO) that accredits the subject. For revocation, use the same value as in the original publication.
attributeIdTao	hexstring	✅	attributeId of the parent TAO accreditation in the TIR (prefixed with 0x).

Successful response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "from": "0x8445fC96e27ceB0d1794be16a1Ac8BF5D765AACB",
    "to": "0x00000000000000000000000000000000000015Be",
    "data": "0x250f4d97...",
    "value": "0x0",
    "nonce": "0xb1d3",
    "chainId": "0x...",
    "gasLimit": "0x1000000",
    "gasPrice": "0x0"
  }
}

The result is an unsigned transaction. The to field is the TIR contract address.

Common errors

Code	Cause
-32600	Invalid or missing API Key.
-32602	Missing parameter, invalid Ethereum address, incorrectly formatted DID, unknown issuerType.

---

setAttributeData

Builds an unsigned transaction that stores the complete accreditation JWT (hex-encoded) in the TIR contract. Must be executed after setAttributeMetadata for the same attribute.

Request

{
  "jsonrpc": "2.0",
  "method": "setAttributeData",
  "params": [
    {
      "from": "0xD442e39AAd178Ec9DfD039aD048203D5d0122e61",
      "did": "did:isbe:uc:zpxbBfHYA5GN45rS1tSEBJg",
      "attributeId": "0x3f4143c6f3a1c79bb32f45a6cbd90ee6bb2e2e71eadda99e371a4a144c53050f",
      "attributeData": "0x65794a6862476369..."
    }
  ],
  "id": 2
}

Parameters

Field	Type	Mandatory	Description
from	address	✅	Ethereum address of who signs the transaction.
did	did	✅	DID of the subject to which the attribute belongs.
attributeId	hexstring	✅	Same revisionId used in setAttributeMetadata for this attribute.
attributeData	hexstring	✅	Accreditation JWT encoded as a hex string with 0x prefix. To convert: "0x" + Buffer.from(jwt_string).toString("hex").

attributeData encoding

The JWT generated by the CLI must be converted to hexadecimal before sending it. In Node.js:

const jwt = "eyJhbGciOiJFUzI1NiIs...";
const attributeData = "0x" + Buffer.from(jwt, "utf8").toString("hex");

Successful response

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "from": "0xD442e39AAd178Ec9DfD039aD048203D5d0122e61",
    "to": "0x00000000000000000000000000000000000015Be",
    "data": "0x...",
    "value": "0x0",
    "nonce": "0xb1d4",
    "chainId": "0x...",
    "gasLimit": "0x1000000",
    "gasPrice": "0x0"
  }
}

---

sendSignedTransaction

Sends an already-signed transaction to the ISBE blockchain and returns the transaction hash. Use it to send each of the unsigned transactions obtained with setAttributeMetadata and setAttributeData.

The transaction is not processed immediately

sendSignedTransaction returns the hash as soon as the transaction enters the mempool. It does not guarantee that it has been included in a block or that it succeeded. You must query the receipt with eth_getTransactionReceipt and verify that status = 0x1.

Request

{
  "jsonrpc": "2.0",
  "method": "sendSignedTransaction",
  "params": [
    {
      "protocol": "eth",
      "unsignedTransaction": {
        "from": "0x8445fC96e27ceB0d1794be16a1Ac8BF5D765AACB",
        "to": "0x00000000000000000000000000000000000015Be",
        "data": "0x250f4d97...",
        "nonce": "0xb1d3",
        "chainId": "0x...",
        "gasLimit": "0x1000000",
        "gasPrice": "0x0",
        "value": "0x0"
      },
      "r": "0xf5649febb203...",
      "s": "0x22d5188b34c3...",
      "v": "0x1B",
      "signedRawTransaction": "0xf9014c..."
    }
  ],
  "id": 3
}

Parameters

Field	Type	Mandatory	Description
protocol	string	✅	Always "eth".
unsignedTransaction	object	✅	Unsigned transaction object exactly as returned by setAttributeMetadata or setAttributeData.
unsignedTransaction.from	address	✅	Ethereum address of the signer. Must match the actual transaction signer.
unsignedTransaction.to	address	✅	TIR contract address.
unsignedTransaction.data	hexstring	✅	Transaction payload (data field from the setAttributeMetadata/setAttributeData result).
unsignedTransaction.nonce	hexstring	✅	Transaction nonce.
unsignedTransaction.chainId	hexstring	✅	ISBE network chain ID.
unsignedTransaction.gasLimit	hexstring	✅	Gas limit.
unsignedTransaction.gasPrice	hexstring	✅	Gas price (normally "0x0" in ISBE).
unsignedTransaction.value	hexstring	✅	Value in wei ("0x0").
r	hexstring	✅	r component of the ECDSA signature.
s	hexstring	✅	s component of the ECDSA signature.
v	hexstring	✅	v component of the ECDSA signature.
signedRawTransaction	hexstring	✅	Complete serialized and signed transaction.

Server validations

The server verifies that:

• signedRawTransaction is consistent with unsignedTransaction + (r, s, v).
• The signer recovered from the signature matches unsignedTransaction.from.
• The transaction chainId matches that of the server's network.
• The to field points to the TIR contract configured on the server.

If any of these validations fail, the server returns -32602 without sending the transaction to the blockchain.

Successful response

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331"
}

The result is the transaction hash. Use it to query the receipt.

Query the transaction receipt

Query the Besu endpoint with the eth_getTransactionReceipt method:

curl -X POST <besu-rpc-url> \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getTransactionReceipt",
    "params": ["0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331"],
    "id": 1
  }'

Relevant receipt fields:

• status: "0x1" = success, "0x0" = failure.
• revertReason: reason for failure (if status = 0x0).

---

REST endpoint: read an accreditation

GET <base-url>/v1/issuers/{did}/attributes/{attributeId}

Authentication: none.

Path parameters:

Parameter	Description
did	DID of the accreditation subject.
attributeId	Attribute identifier in the TIR. Without the 0x prefix.

Response 200 OK:

{
  "did": "did:isbe:uc:zpxbBfHYA5GN45rS1tSEBJg",
  "attribute": {
    "body": "eyJhbGciOiJFUzI1NiIs...",
    "hash": "3f4143c6f3a1c79bb32f45a6cbd90ee6bb2e2e71eadda99e371a4a144c53050f",
    "issuerType": "TI",
    "rootTao": "did:isbe:uc:z12kVar5p6bD5WCjEJcQ18Zyt8XV",
    "tao": "did:isbe:uc:zj4sk7oEMx1SGNAzibWxVAV"
  }
}

Field	Description
did	Subject's DID.
attribute.body	Accreditation JWT (Base64url).
attribute.hash	Attribute hash in the TIR (without 0x prefix). Matches the attributeId.
attribute.issuerType	Role type: RTAO, TAO, TI, or REVOKED.
attribute.rootTao	DID of the root RTAO of the chain.
attribute.tao	DID of the immediately superior TAO.

Errors:

Code	Cause
404 Not Found	The DID or the attributeId do not exist in the TIR.
400 Bad Request	The attributeId contains non-hexadecimal characters.

---

Health endpoint

GET /health

Authentication: none.

Response 200 OK:

{
  "status": "ok",
  "uptime": 12.34
}

---

Metrics endpoint

GET /metrics

Exposes metrics in Prometheus format for monitoring with Grafana.

Authentication: none.