Usage Recommendations

Conventions that apply to every FaceAuthen endpoint: how to make requests reconcilable with CAKE, and the fixed vocabularies for image labels and card types that the APIs validate against.

API Reconciliation

To make reconciliation between your system and the CAKE service straightforward, send an X-Request-Id header on every call.

What	Description
X-Request-Id	A client-generated request identifier. You generate and manage its value; CAKE stores what it received so both sides can be compared and mismatches surfaced.

Use a random, non-repeating UUID for every request (shown as <RANDOM_UUID> in the samples). Don't put a user ID or any other personal data in it — the value is stored and logged on both sides. Keep your own mapping from the UUID to the user if you reconcile per user.

Use Uploaded Image IDs

Upload each image once via Upload Image and pass the returned image_id to every other API, rather than re-sending base64 bytes on each call. This keeps requests small, avoids duplicate storage, and lets CAKE correlate all checks performed on the same image.

Image Labels

The label field MUST be one of the following values.

Label	Description
portrait	The portrait (selfie) photo
portrait_nfc	The portrait photo read from the NFC chip
qr_code	The QR code image
id_card.vn.national_id.front	The front side of a Vietnam card (CMND old/new, CCCD, Passport)
id_card.vn.national_id.back	The back side of a Vietnam card (CMND old/new, CCCD, Passport)
doc.vn.business_license	The business licence image

Card Types

The card_type field MUST be one of the following values.

Card type	Description
vn.cccd_new	Căn cước công dân
vn.cc_new	Căn cước
vn.other	Does not match any defined type

INFO

Sample requests throughout these docs use card_type: "vn.national_id". Confirm the exact set of card types enabled for your tenant with CAKE Support before going live.

Image Metadata

Several endpoints accept a metadata field on an image. It is a JSON string holding a flat key/value dictionary, where keys are strings and values are string, int, float or bool.

"{\"id\":\"<ID>\",\"type\":1}"

For a QR code image, metadata can carry the raw decoded string:

"{\"raw\":\"<decoded QR content>\"}"

Where a request accepts an image object, supply either id or base64:

• If you pass base64, also pass label and metadata, and omit id.
• If you pass id (returned by Upload Image), omit base64, label and metadata.

Next Steps

• Upload Image — obtain the image_id these conventions depend on
• FaceAuthen Overview — authentication, response envelope and the end-to-end flow