API REST — Dokumentasi VerixID

Autentikasi

Base URL: https://api.verixid.com

VerixID adalah mathematical witness untuk file digital. API ini menerima fingerprint (SHA-256 hash) file, bukan file itu sendiri — file tidak pernah diupload ke server (zero-custody).

🔑

Semua endpoint mewajibkan API key, dikirim lewat header X-Secure-Key: <64-karakter-api-key>. Key didapat dari dashboard VerixID — generate sekali, ditampilkan sekali saat itu juga. Simpan dengan aman, jangan pernah tempel di chat, repo publik, atau log.

· Format: 64 karakter alfanumerik (A-Z, a-z, 0-9), case-sensitive.

Mendaftarkan File

POST /submit

Mendaftarkan fingerprint file baru ke ledger.

Headers

Content-Type: application/json X-Secure-Key: <api-key>

Body

{ "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" }

Field	Wajib	Keterangan
`hash`	Ya	SHA-256 hex, 64 karakter. Dihitung di sisi client — file tidak pernah dikirim.

Batasan: ukuran payload maksimum 10 KB · rate limit 20 request/menit. Submit dibatasi berdasarkan kuota paket selama periode langganan.

Response sukses — 201 Created

{ "record_id":"vx202607026731ce", "server_timestamp":"2026-07-21T12:54:59.469Z", "receipt_signature":"...", "ownership_key":"..." }

Simpan record_id — identifier publik untuk verifikasi. Ownership key (kalau ada di response) simpan aman; itu bukti kepemilikan pribadi dan tidak bisa dipulihkan jika hilang.

Hash sudah pernah terdaftar

409 Conflict

Verifikasi Record

GET /verify

Memverifikasi keberadaan record — bisa dipakai siapa saja yang punya record_id.

GET /verify?id=vx202607a1b2c3d4 GET /verify?id=vx202607a1b2c3d4&ownership_key=<64-hex>

Param	Wajib	Keterangan
`id`	Ya	Format: `vx` + `YYYYMM` + 8 karakter hex. Contoh: `vx202607a1b2c3d4`.
`ownership_key`	—	64 karakter hex. Kalau valid, dapat proof kepemilikan.

Endpoint ini tetap dilindungi Fair Usage Policy (rate limiting dan proteksi abuse).

Mode 1 — tanpa ownership_key (public check)

{ "record_id": "vx202607a1b2c3d4", "registered_at": 1784375908188, "hash_preview": "f8bd8b98730d5c19...", "ownership_verified": false }

hash_preview cuma 16 karakter pertama — mencegah brute-force identitas file dari publik.

Mode 2 — dengan ownership_key valid (proof kepemilikan)

{ "record_id": "vx202607a1b2c3d4", "registered_at": 1784375908188, "hash_preview": "d5fc7d44cb58413b2c9d9c4e66722a031080279d9c25c9bb88f6c2e0d17439fb", "ed25519_signature": "4b6bd41e1dc082fa02f4081374...", "ownership_verified": true }

hash_preview sekarang hash lengkap (64 karakter), plus ed25519_signature (hex, 128 karakter — 64 byte) yang bisa diverifikasi independen memakai public key VerixID di /.well-known/verixid-public-key.pem.

Record tidak ditemukan

404 Not Found

Format Error

Semua error mengikuti struktur konsisten:

{ "code": "invalid_hash", "title": "Invalid Hash", "status": 400, "detail": "Hash must be a SHA-256 hex string (64 characters)." }

code	Status	Kapan terjadi
`unauthorized`	401	API key kosong, salah format, atau tidak terdaftar
`billing_expired`	402	Akun suspend atau periode billing berakhir
`invalid_json`	400	Body bukan JSON valid
`invalid_hash`	400	`hash` bukan SHA-256 hex 64 karakter
`invalid_id`	400	`id` bukan format record ID yang valid
`invalid_key` / `invalid_ownership_key`	400	`ownership_key` bukan hex 64 karakter
`payload_too_large`	400	Body request > 10 KB
`quota_exceeded`	429	Kuota bulanan habis
`rate_limit_exceeded`	429	Lebih dari 20 request/menit
`method_not_allowed`	405	Method HTTP salah untuk endpoint tsb
`not_found`	404	Path tidak dikenal
`upstream_error`	502	Layanan internal bermasalah, coba lagi
`internal_error`	500	Error tak terduga

Contoh cURL

Submit

curl -X POST https://api.verixid.com/submit \ -H "X-Secure-Key: <api-key>" \ -H "Content-Type: application/json" \ -d '{ "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" }'

Verify (public)

curl "https://api.verixid.com/verify?id=vx202607a1b2c3d4" \ -H "X-Secure-Key: <api-key>"

Verify (dengan ownership proof)

curl "https://api.verixid.com/verify?id=vx202607a1b2c3d4&ownership_key=<64-hex-key>" \ -H "X-Secure-Key: <api-key>"

💡

Jangan tempel API key produksi di terminal history, chat, atau repo publik. Kalau tidak sengaja ter-expose, rotate key dari dashboard.

Yang Perlu Anda Tahu

Zero-Custody: File asli tidak pernah dikirim/disimpan, hanya SHA-256 fingerprint-nya.
Verify, Don't Trust: Hasil deterministik, bisa diverifikasi ulang secara independen (SHA-256 + Ed25519) tanpa perlu percaya ke VerixID.
Append-Only: Sekali submit, record tidak bisa dihapus/diubah. Uji coba dengan hash dummy tetap tercatat permanen di ledger.
Bukan Ini: Bukan e-signature, bukan blockchain, bukan KYC — murni bukti integritas & waktu keberadaan file.