API Basics
Your backend calls the REST API from TCS (TCS API for DIW). With it, you can issue, verify, and revoke credentials in the Taiwan Digital Identity Wallet (TW DIW, “the wallet” in this handbook).
This handbook uses these two terms:
- Verification scenario (VP Template): specifies which credentials and fields the holder must present. Its code is
ref. - Credential type (VC Template): defines the fields of a credential and its validity period. Its code is
vc_uid.
The TCS team creates both codes and gives them to you. For how to request them, see Getting Started.
Production base URL:
https://diw.turingspace.coAll paths start with /v1, for example POST https://diw.turingspace.co/v1/diw/verifications.
Request and response bodies are JSON. Field names use snake_case. These names are exceptions: statusCode and correlationId in error responses, and statusRevoke and cidNotFound in warnings. Read them with the names that each page lists. Do not convert the naming format automatically. When you send a POST request, include Content-Type: application/json.
No test environment is available at this time.
Send the API Key with every request
Section titled “Send the API Key with every request”Put the API Key in the X-API-Key request header. If the API Key has a problem, the API returns 401. The message gives the reason:
message | Meaning | What you do |
|---|---|---|
API Key is required | The request does not include X-API-Key. | Add the header. |
Invalid API Key | This API Key does not exist. | Check that you copied the full API Key. |
API key has expired (grace window passed) | This API Key is no longer valid. | Use the new API Key from the TCS team. If you do not have it yet, contact the TCS team. |
Account is not approved | This account cannot use the API at this time. | Contact the TCS team. |
Authentication failed | An error occurred on the TCS side when TCS checked the API Key. This error does not always mean that your API Key has a problem. | Send the request again later. If your API Key is correct and the error continues, contact the TCS team with the request time and the x-correlation-id. |
Keep the API Key only on your backend servers. Putting it in a front-end environment, such as a web app or a mobile app, is not recommended. Users can get the code that runs there, so the API Key may leak.
Send x-correlation-id and x-request-id with every request
Section titled “Send x-correlation-id and x-request-id with every request”x-correlation-id is a tracking value that you generate, for example a new UUID for each request. When the API returns an error (4xx or 5xx), the error response contains this value in the correlationId field.
Put the same value in x-request-id too. The TCS logs record every request by its x-request-id, successful requests included. If a response is lost, the TCS team needs this value to find the request. If you send only x-correlation-id, successful requests cannot be found by this value in the logs. When you contact the TCS team, give the request time and this value.
curl -X POST https://diw.turingspace.co/v1/diw/verifications \ -H "X-API-Key: <your-api-key>" \ -H "x-correlation-id: <your-correlation-id>" \ -H "x-request-id: <your-correlation-id>" \ -H "Content-Type: application/json" \ -d '{"ref": "<ref>"}'If you get 201, the URL and the API Key are correct. For the response and how to poll, see Verification API. For issuance, see Issuance API.
Error response format:
{ "statusCode": 404, "message": "verification not found", "error": "Not Found", "timestamp": "2026-10-16T03:12:45.123Z", "path": "/v1/diw/verifications/<id>", "correlationId": "<your-correlation-id>"}If the request does not include x-correlation-id, the response has no correlationId field. A 502 response is sometimes plain text, not this format. For this reason, write the x-correlation-id to your log before you send the request.
For the meaning of each status code and what to do, see Errors and Polling.
Store ids exactly as you get them and send them back unchanged
Section titled “Store ids exactly as you get them and send them back unchanged”The API gives you three types of id:
| id | When and where you get it | Use |
|---|---|---|
Issuance request id | In the response when you create an issuance request (POST /v1/diw/issuances) | Query the acceptance status |
Credential cid | In the response when you query an issuance request and the status is issued (GET /v1/diw/issuances/{id}) | Revoke this credential. Put it in cids when you renew a credential. |
Verification request id | In the response when you create a verification request (POST /v1/diw/verifications) | Query the verification result |
The issuance result also returns credential_serial (the credential serial number). You do not send it back to the API. You use it only to compare with data[].cid during verification. See Verification API.
- Store the full value. Do not change any character, and do not change its case. No id is longer than 128 characters. Set the length of your database column to match.
- Only the account that got an id can use it to query or revoke. If you use the API Key of a different account, you get
404. - If the id format is not correct, you get
400. If the format is correct but the content was changed, you get404.
Give the QR code or the mobile link to the holder
Section titled “Give the QR code or the mobile link to the holder”After you create an issuance or a verification, the response contains two values. They have the same content but different uses. The mobile link is deep_link in the issuance response and auth_uri in the verification response.
| Field | Where to use it |
|---|---|
qrcode_image | Desktop web pages. The value is a data URI of a base64 PNG. You can put it directly in <img src> so that the recipient or the holder can scan it with a phone. |
deep_link (issuance) / auth_uri (verification) | Mobile link. When the recipient or the holder opens this https link on a phone, the phone opens the wallet app. |
<img src="data:image/png;base64,iVBORw0K..." alt="Scan this QR code with the wallet" />After the recipient or the holder scans, the wallet and TCS complete the next steps. Your backend does not get a notification. Poll for the result with GET. For the polling interval, see Errors and Polling.