Issuance API
The issuance flow: you send the credential fields. The recipient scans with the Taiwan Digital Identity Wallet (TW DIW, “the wallet” in this handbook) and accepts the credential. Your backend polls TCS API for DIW until the status becomes issued. Then you store the cid of this credential. The credential shows Turing Space Inc. as the issuer, not your organization. After the recipient accepts the credential, the recipient is the holder of that credential.
You cannot use the API to specify who accepts the credential. Give the QR code and the mobile link only to the intended recipient.
In the diagram, par means that the steps occur at the same time, loop means that the steps repeat, and alt means that only one of the paths occurs, depending on the situation.
Create an issuance
Section titled “Create an issuance”POST /v1/diw/issuances| Field | Type | Required | Description |
|---|---|---|---|
vc_uid | string | Yes | The code of the credential type (VC Template). Your organization requests it, and the TCS team creates it and gives it to you. See Request new credential types and verification scenarios. If no credential type has this code, you get 10108. If the credential type is no longer issued, you get 11007. |
fields | array | Yes | The credential fields. Each item is {ename, content}. |
fields[].ename | string | Yes | The field name in English (欄位名稱(英)). It must be exactly the same as the ename in the credential type. |
fields[].content | string | Yes | The field value. It is always a string. Boolean values are also text, for example true / false. |
issuance_date | string | No | The issue date, format YYYYMMDD, Taiwan time. It must not be a future date. The credential is valid from 00:00:00 on this day. If you do not send it, the issue date is today. If it is not 8 digits, you get 400 with no module error code. If it is 8 digits but not a real date (for example 20261340), you get 10109. If the date is in the future, you get 10113. |
expired_date | string | No | The expiry date, format YYYYMMDD, Taiwan time. The credential becomes invalid at 23:59:59 on this day. If you do not send it, the validity period of the credential type applies, starting when the recipient scans the QR code. It must not be earlier than today or earlier than the creation date of the credential type. If it is not 8 digits, you get 400 with no module error code. If it is 8 digits but not a real date, you get 10109. If the date is too early, you get 10114. |
cids | string[] | No | The cid values of old credentials to revoke with this issuance. Use it when you renew a credential. See “Renewal: revoke old credentials when you issue a new one” below. |
Rules for fields:
- Put all required fields in
fields. If a required field is missing, or its value is an empty string, you get400and themessagestarts withissuer module 11001. If an optional field has no value, you can leave it out or send an empty string. - Do not send fields that the credential type does not define. If you do, you get
400and themessagestarts withissuer module 10112. - Put the fields in the order that you want on the card face. The API does not change the order. The value of the first field shows on the card face.
contentmust match the rules of its field. If it does not match, you get400and themessagestarts withissuer module 10110. The error message does not say which field is wrong.- The basic field 姓名 (
name, full name) accepts only Chinese, English letters, digits, and_. If the value contains a space, for example between the parts of an English name, you get10110.
{ "vc_uid": "<vc_uid>", "fields": [ { "ename": "name", "content": "王小明" }, { "ename": "department", "content": "研發部" }, { "ename": "position", "content": "工程師" }, { "ename": "employee_id", "content": "A12345" } ], "expired_date": "20271031"}On success, you get 201:
{ "id": "<id>", "qrcode_image": "data:image/png;base64,iVBORw0K...", "deep_link": "https://frontend.wallet.gov.tw/api/moda/vcqrcode?mode=vc01&deeplink=...", "warnings": null}| Field | Description |
|---|---|
id | The id of this issuance. Send the full value back when you query the acceptance status. |
qrcode_image | The QR code image (base64 PNG data URI) to show on desktop web pages. |
deep_link | The mobile link. It opens the wallet app on a phone. It has the same content as the QR code. |
warnings | Warnings about cids. If you do not send cids, it is null. For the format, see “Renewal: revoke old credentials when you issue a new one” below. |
Store the id, qrcode_image, and deep_link together. If the recipient waits too long, you may need to show the same QR code or mobile link again.
Poll the acceptance status
Section titled “Poll the acceptance status”GET /v1/diw/issuances/{id}If the recipient has not accepted the credential, you get 200:
{ "status": "pending", "id": "<id>"}After the recipient accepts the credential, you get 200:
{ "status": "issued", "id": "<id>", "credential": "eyJqa3UiOi...", "cid": "<cid>", "credential_serial": "<credential_serial>"}status has two values only:
pending: the recipient has not scanned or has not accepted the credential. Query again after 2 to 5 seconds.issued: the recipient accepted the credential.
| Field | Description |
|---|---|
credential | The signed credential (SD-JWT format). TCS passes it to you unchanged. This string does not contain the field values. |
cid | The identifier of this credential. You need it to revoke or renew the credential. |
credential_serial | The serial number of this credential. The wallet shows it as 「憑證序號」 (“VC No.” in English). Compare it with data[].cid when you verify. See Verification API. |
Only the account that created this issuance request can query the result. If you use the API Key of a different account to query the same id, you get 404. For other cases that return 400 or 404, see Errors and Polling.
If the recipient takes too long
Section titled “If the recipient takes too long”If the recipient does not scan or does not accept the credential, the status stays pending (waiting) for the full timeout that you set. Set your own timeout. The recommended value is 5 minutes. This timeout only closes your waiting screen. It does not cancel the issuance. The recipient may still scan the original QR code later and accept the credential.
After the waiting screen closes, keep the issuances that have no result yet on a to-do list. Query them again later until the status becomes issued.
Before you issue again to the same person, do these steps:
- Keep the
idof the original issuance. Do not discard it. - Query the status again with this
id. - If the status is
issued, store thecid. Do not issue again. - If the status is still
pending, show the storedqrcode_imageordeep_linkagain. Ask the recipient to accept the credential with it. Do not create a new issuance. If the wallet does not accept the original QR code or mobile link, create a new issuance and follow step 5. - If you still must create a new issuance, both issuances may become
issuedlater. In this case, revoke the extra credential with itscid.
Store the cid and the credential_serial
Section titled “Store the cid and the credential_serial”When you get issued, store the full cid and credential_serial in your database immediately and link them to your own user. You need them later to:
- Revoke this credential with the
cid. - Put the
cidincidswhen you renew the credential. - Compare the
credential_serialwithdata[].cidduring verification, to make sure that the holder presented this credential.
If you lose the cid and you still have the id of the issuance, query GET /v1/diw/issuances/{id} again. If the result is still issued, you get the same cid and credential_serial. The API currently cannot list the credentials that you issued, so store the cid the first time that you get issued.
Do not automatically resend a request to create an issuance
Section titled “Do not automatically resend a request to create an issuance”If you send POST /v1/diw/issuances twice, you create two issuances (this API is not idempotent).
In these cases, the issuance may already exist:
- You get
502or another5xx. - Your HTTP client reaches its timeout.
- The connection breaks, or the response is lost in transit, and you get no response.
If TCS does not complete the request within 5 seconds, it returns 502. Set the timeout of your HTTP client to more than 5 seconds, for example 10 seconds. Then you are more likely to get 502 than no response.
You cannot use the API to check whether the issuance exists, because the API currently cannot list issuances. In all of the cases above:
- Do not resend automatically. If your HTTP client, SDK, or API gateway automatically resends a request after it fails, turn off these automatic resends for the API that creates issuances. This prevents the same issuance from being created twice.
- Record the time you sent the request and the
x-correlation-id/x-request-idvalue that you sent. - Contact the TCS team. The TCS team will check for you.
400 means that the API rejected the request content. Correct the request as the error message tells you, and then send it again. For common error codes, see Errors and Polling.
Renewal: revoke old credentials when you issue a new one
Section titled “Renewal: revoke old credentials when you issue a new one”A new credential does not replace an old one. One holder can have more than one valid credential of the same credential type. If you want to keep only one credential for each person (for example, an employee card), put the cid of the old credential in cids when you issue the new one. If a person can have more than one (for example, a certificate for each event), do not send cids.
Put the cid values of the old credentials in cids. When the recipient accepts the new credential, those old credentials are revoked. If the recipient does not accept it, the old credentials stay valid. Rules for cids:
- Use the full
cidthat you got at issuance. Do not remove any part. If the format is not correct, you get400. - If a
cidwas not issued by your account, you get404. - If any item is not correct, the API does not issue the credential and does not revoke any old credential.
If an old credential is already revoked, or the system cannot find the credential, the request still succeeds, and warnings lists these credentials. warnings is an object with two fields. Each field is an array, or null when no credential applies:
| Field | Content |
|---|---|
warnings.statusRevoke | Old credentials that are already revoked |
warnings.cidNotFound | Old credentials that the system cannot find |
warnings lists credential serial numbers, not cid values. Use the credential_serial that you stored at issuance to find the old credential.
If a request with cids gets 502 or another 5xx, or gets no response, the new issuance may already exist. The old credentials are revoked only when the recipient accepts the new credential. Do the same as in the previous section: do not resend automatically, and contact the TCS team.