API Reference

DXA Trustway API

Niêm phong nguồn gốc cho chứng từ & kết quả AI

DXA Trustway là cổng an toàn (Secure Gateway) gắn vào mỗi chứng từ hay kết quả AI một bằng chứng số trả lời: ai đã cấp và nó có còn nguyên vẹn không. Trustway ký manifest (P-256 + secp256k1), phát hành biên nhận (receipt), neo dấu vân tay lên DXA Blockchain, và cho phép xác minh độc lập — không cần dữ liệu gốc.

Base URL

https://trustway.dxa.io.vn

Xác thực

Niêm phong dùng phiên SSO `xv_session` (issuer lấy từ DXA Identity; chế độ demo cho phép `issuerId` mẫu). Thao tác giá trị cao (Tier 2+) có thể yêu cầu nâng mức đảm bảo (AAL3, passkey). Xác minh và JWKS là công khai. Khóa relayer on-chain do DXA Blockchain giữ — Trustway không giữ khóa on-chain.

Niêm phong & Xác minh

POST /api/seal

Ký & niêm phong một kết quả AI kèm danh tính issuer

Xác thực: Phiên SSO `xv_session` (hoặc demo)

Tham số (body)

Trường	Kiểu	Mô tả
`modelId`*	`string`	ID mô hình, vd `claude-3-sonnet`
`output`*	`any`	Kết quả/quyết định AI cần niêm phong
`input`	`object`	Đầu vào mô hình (sẽ băm SHA-256, không lưu mặc định)
`tier`	`number`	Mức tier (mặc định 1); Tier 2+ có thể cần step-up
`anchorNow`	`boolean`	Neo manifest lên blockchain ngay

Ví dụ yêu cầu

curl -X POST 'https://trustway.dxa.io.vn/api/seal' \
  -H 'Content-Type: application/json' \
  -H 'Cookie: xv_session=<token>' \
  -d '{ "modelId": "claude-3-sonnet", "output": { "decision": "approve" }, "anchorNow": true }'

Phản hồi mẫu

{
  "receiptId": "rcpt_8a1…",
  "outputHash": "sha256-…",
  "manifestHash": "sha256-…",
  "issuerId": "org_12ab",
  "issuerName": "Đối tác ABC",
  "identityVerified": true,
  "authLevel": "AAL2",
  "p256Sig": "…",
  "ethSig": "0x…",
  "anchor": { "mode": "onchain", "txHash": "0x…", "explorerUrl": "https://sepolia.basescan.org/tx/0x…" }
}

Mã lỗi

`400`	Thiếu `modelId` hoặc `output`
`403 stepup_required`	Chứng từ giá trị cao cần xác thực chống lừa đảo (AAL3)

GET /api/verify

Xác minh bằng chứng theo receiptId

Xác thực: Không (công khai)

Tham số

Tên	Kiểu	Mô tả
`receiptId`*	`string`	ID biên nhận (`rcpt_…`)

Phản hồi mẫu

{
  "status": "valid",
  "manifestHash": "sha256-…",
  "issuer": { "orgId": "org_12ab", "orgName": "Đối tác ABC", "verified": true },
  "anchor": { "onChain": true, "txHash": "0x…" }
}

POST /api/verify

Xác minh bằng manifest JSON (+ public JWK tuỳ chọn)

Xác thực: Không (công khai)

Tham số (body)

Trường	Kiểu	Mô tả
`proof`*	`string`	Manifest JSON đã tuần tự hóa (claim + chữ ký)
`publicJwk`	`object`	JWK để kiểm chữ ký (mặc định lấy từ /api/keys/jwks)

Phản hồi mẫu

{ "status": "valid", "integrity": "intact", "issuer": { "orgId": "org_12ab" } }

Neo & Chứng thực

POST /api/anchor

Neo manifest hash lên DXA Blockchain

Xác thực: Không (công khai)

Tham số (body)

Trường	Kiểu	Mô tả
`receiptId`*	`string`	ID biên nhận cần neo

Phản hồi mẫu

{ "mode": "onchain", "txHash": "0x…", "ref": "0x…", "explorerUrl": "https://sepolia.basescan.org/tx/0x…" }

POST /api/attestation

Phát hành attestation đã ký (định dạng kiểu EAS)

Xác thực: Không (issuer từ body hoặc demo)

Tham số (body)

Trường	Kiểu	Mô tả
`schema`*	`string`	URI schema attestation
`subject`*	`string`	DID/ID đối tượng
`claim`*	`any`	Dữ liệu claim (sẽ băm & ký)

Phản hồi mẫu

{
  "attestationId": "att_8a1…",
  "digest": "sha256-…",
  "sig": "…",
  "verifyUrl": "https://trustway.dxa.io.vn/verify/rcpt_8a1…"
}

GET /api/keys/jwks

Công bố khóa công khai issuer (P-256 + địa chỉ ETH)

Xác thực: Không (công khai)

Phản hồi mẫu

{
  "keys": [
    {
      "kid": "org_12ab",
      "did": "did:web:identity.dxa.io.vn:o:org_12ab",
      "jwk": { "kty": "EC", "crv": "P-256", "x": "…", "y": "…" },
      "ethAddress": "0x…"
    }
  ]
}