Link Search Menu Expand Document
tsrct documentation

Creating Private Documents (A2A & B2B)

The Tsrct protocol allows you to publish documents that are strictly controlled and only viewable by intended recipients. By utilizing Access Control Lists (acl) and Target (tgt) fields, you can securely send private payloads (like invoices, proprietary settlement data, or confidential A2A messages) across the network.

The Authorization Model

When a document is marked as private, the Tsrct API acts as a secure gatekeeper.

  1. Creation: The publisher specifies acl_pri (Private) and sets the tgt (Target) field to the 25-digit UID of the intended recipient.
  2. Retrieval: When someone attempts to fetch the T-Doc via the API, the Tsrct Engine intercepts the request.
  3. Verification: The requester must provide a valid X-TSRCT-AUTH JWT header. The API verifies the JWT, extracts the caller’s UID (src), and compares it against the document’s tgt field. If they match, the document is served; otherwise, the request is rejected with a 401 Unauthorized or 404 Not Found (to obscure the existence of the document).

1. Prepare Your Payload

Create your payload file (e.g., confidential-report.json):

{
  "reportId": "Q3-FIN-0912",
  "status": "CONFIDENTIAL",
  "data": {
    "revenue": 1450000,
    "expenses": 980000
  }
}

2. Issue the T-Doc via CLI

Use the tsrct tdoc doc-create command. The critical flags for privacy are --acl acl_pri and --tgt <RECIPIENT_UID>.

tsrct tdoc doc-create \
  --typ json \
  --cty application/json \
  --input confidential-report.json \
  --src <YOUR_ORG_UID> \
  --tgt <RECIPIENT_ORG_UID> \
  --uid confidential-report-001 \
  --dsc "Q3 Financial Report" \
  --acl acl_pri \
  --lst false \
  --key <YOUR_KEY_ID> \
  --key-host gcp \
  --sig-key-resource <YOUR_GCP_KMS_SIGNATURE_KEY_RESOURCE_PATH>

Key Privacy Flags:

  • --acl acl_pri: Sets the Access Control List to private. The document will not be served to anonymous API requests.
  • --tgt <RECIPIENT_ORG_UID>: Specifies the exact UID of the user or organization authorized to retrieve this document.
  • --lst false: Optional but highly recommended. Ensures the document does not appear in any public feeds, directories, or paginated search results, even for the recipient (they must know the specific UID to request it).

Note:

  • --uid of the document will be set as <YOUR_ORG_UID>.<DOCUMENT_UID>; this will be referred to as <FULL_DOCUMENT_UID> in the following examples

3. Retrieving the Private Document

When the recipient (the entity matching the <RECIPIENT_ORG_UID>) wishes to read the document, they cannot simply perform a standard HTTP GET. They must authenticate.

Using the Tsrct CLI

The recipient can use the dl (download) command, which will automatically handle the JWT generation and injection if their local CLI environment is authenticated.

tsrct dl --uid <FULL_DOCUMENT_UID>

Using HTTP / cURL (Custom Integration)

If the recipient is integrating directly via an automated system or API client, they must construct and sign a JSON Web Token (JWT) using their registered Tsrct API key and include it in the X-TSRCT-AUTH header.

The JWT must be signed using the RS256 algorithm.

Required JWT Payload Structure:

The payload of your JWT must precisely match the parameters of the request you are making:

{
  "iss": "<RECIPIENT_ORG_UID>",
  "aud": "2222222222222222222222222", 
  "key": "<RECIPIENT_KEY_UID>",
  "act": "GET:/<FULL_DOCUMENT_UID>",
  "nce": 1777813500,
  "nbf": 1777813500,
  "exp": 1777813560
}

JWT Field Breakdown:

  • iss (Issuer): Must be the 25-digit UID of the recipient (matching the tgt of the document).
  • aud (Audience): Must be the exact UID of the Tsrct network environment (e.g., 2222222222222222222222222 for tsrct.io).
  • key: The Tsrct UID of the public key registered in the network that corresponds to the private key you are using to sign this JWT. It must be prefixed by your iss UID (e.g., <RECIPIENT_ORG_UID>/key/1).
  • act (Action): The exact HTTP method and URI path being requested. For retrieving a document, this is usually GET:/<DOCUMENT_UID>.
  • nce (Nonce): The current Unix timestamp in seconds. Must be within +/- 5 seconds of the server’s current time to prevent replay attacks.
  • nbf (Not Before): Unix timestamp in seconds. The token is invalid before this time.
  • exp (Expiration): Unix timestamp in seconds. The token is invalid after this time.

Optional: CIX DDX Proofs

If the document you are retrieving is secured by a Confidential Information Exchange (CIX) policy rather than a direct tgt assignment, you must include cryptographic proof of your active DDX credentials.

These proofs are embedded in the JWT Header (not the payload) under the custom ddx array. Each object in the array represents a single, actively countersigned DDX credential.

Example JWT Header with ddx Proofs:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "<RECIPIENT_KEY_UID>",
  "ddx": [
    {
      "uid": "<DDX_GRANT_UID>",
      "req": {
         "sig": "<CLIENT_SIG_OVER_CHALLENGE>",
         "sha": "<SHA_OF_PAYLOAD>",
         "src": "<CLIENT_UID>",
         "key": "<CLIENT_KEY_UID>",
         "nce": 1777813500,
         "val": "sig=<SIG>&sha=<SHA>&src=<SRC>&nce=<NCE>"
      },
      "res": {
         "val": "sig=<SIG>&sha=<SHA>&src=<SRC>&nce=<NCE>&its=<TIMESTAMP>",
         "sig": "<DDX_PROVIDER_COUNTERSIGNATURE>",
         "sha": "<SHA_OF_RES_VAL>",
         "its": "<TIMESTAMP>",
         "bld": "1.0.0"
      }
    }
  ]
}

(By placing the ddx array in the JWT header, standard JWT libraries remain compliant, while the Tsrct API securely verifies the countersignatures before granting access to the CIX document.)

Once the JWT is generated and signed, you can execute your cURL request. There are three primary endpoints you can use to retrieve information about the document:

  1. Get the Header Only: GET https://api.tsrct.io/<DOCUMENT_UID> (The act field in your JWT must be GET:/<DOCUMENT_UID>)
  2. Get the Full T-Doc: GET https://api.tsrct.io/<DOCUMENT_UID>/tdoc (The act field in your JWT must be GET:/<DOCUMENT_UID>/tdoc)
  3. Get the Body Payload Only: GET https://api.tsrct.io/<DOCUMENT_UID>/body (The act field in your JWT must be GET:/<DOCUMENT_UID>/body)

Example (Retrieving the full T-Doc):

curl -X GET https://api.tsrct.io/<YOUR_ORG_UID>.confidential-report-001/tdoc \
  -H "X-TSRCT-AUTH: <YOUR_SIGNED_JWT>"

If the JWT is missing, expired, signed by an unregistered key, or if the act does not exactly match the requested path, the API will reject the request and return a 401 Unauthorized message.