Skip to content

Getting Started

The TCS team at Turing Space Inc. handles access to TCS API for DIW and requests for credential types and verification scenarios. At this time, there is no online self-service application process.

  • You already have a TCS API Key: call TCS API for DIW with your current API Key. You do not need to request access separately.
  • You do not have a TCS API Key: contact the TCS team. Tell the TCS team whether you want to issue, verify, or both. After the TCS team activates your access, it issues an API Key to your organization.

Confirm the fees, the time needed to get access, and the request rate limits with the TCS team.

If the credential type or verification scenario that you need does not exist, fill in the field request form below and send it to the TCS team.

Request new credential types and verification scenarios

Section titled “Request new credential types and verification scenarios”

The TCS team creates credential types and verification scenarios. You supply the content. After the TCS team creates them, it gives you the codes. Your engineers use these codes when they call the API.

  • Credential type (VC Template): for issuance. A credential type defines the fields, the card face, and the validity period of a credential.
  • Verification scenario (VP Template): for verification. A verification scenario defines which fields of which credential types the holder must present.

If you only verify credentials, you do not always need to request a new credential type. A verification scenario can ask for credentials that other organizations issued, for example the driver’s license from the Highway Bureau (公路局).

The TCS team assigns the codes of credential types and verification scenarios. The codes start with 83588104_. When you call the API, use the full code that the TCS team gives you. For verification, put it in ref (for example 83588104_example_scenario). For issuance, put it in vc_uid (for example 83588104_example_card). You cannot change the code of a credential type after it is created.

Copy the tables below, fill them in, and send them to the TCS team. The item names are the names in the issuance admin UI, which is in Chinese. Each item also has its English name or API name. The examples in the tables are for an employee card. Replace them with your content.

ItemDescriptionYour value
Organization name (組織名稱)The full registered name of your organization, in Chinese and in English
Privacy policy URL (隱私權政策網址)The URL of the public privacy policy page of your organization. If an English version exists, also give its URL

B. Credential type form (one form for each credential type)

Section titled “B. Credential type form (one form for each credential type)”

Credential type data

ItemDescriptionExample
Credential type name (VC 模板名稱)The credential name on the card face. Give both a Chinese name and an English name. You can use Chinese, English letters, and digits. The card face shows up to 18 characters in full. Characters after that are replaced with ”…”.範例公司員工證/Example Co. Employee Card
Validity period (有效期間)A number and a unit. The period starts when the recipient scans the QR code to accept the credential. The credential becomes invalid after the validity period ends or after it is revoked. You can also set an expiry date for an individual credential when you issue it. The value here is the default.12 months
Card face upload (卡面上傳(卡面圖片,選填)), optionalDesign the image with the card face template file (SVG). Save it as JPG or PNG and provide it. If you do not send an image, the default card face is used. For the specifications, see “Card image specifications” below.Not provided
Public (對外顯示)Yes or no. If you select yes, other organizations can also use this credential type in their verification scenarios to ask holders to present this credential.No

You do not need to fill in the identity assurance level (IAL).

Card image specifications

  • Aspect ratio 1.6:1. Minimum 320 x 200 px. The longest side is not more than 2048 px.
  • File size 40 to 500 KB. JPG or PNG, RGB color, 72 ppi or more.
  • Put text and graphics in the safe area. For a 320 x 200 px card face, this is the center 288 x 168 px.
  • Keep the top-right corner empty. The Taiwan Digital Identity Wallet (TW DIW, “the wallet” in this handbook) shows the certification mark and the credential status there (for example 「已失效」, or “Expired” when the phone language is English).
  • The bottom-left corner is for the value of the first field. Do not put icons or text in that area.
  • The card image can show your organization’s brand. If the image already shows your organization name and the credential name, tell the TCS team. Then the card face does not need to show the issuing organization name and the credential name again.

Before you design, download the card face design guide (Ministry of Digital Affairs, PDF) and the card face template file (SVG, 320 x 200 px). The design guide is from the Ministry of Digital Affairs and is in Chinese only.

Fields

The table below is an example (an employee card). Replace it with your fields.

Field category (欄位類別)Display name, Chinese (欄位對外名稱(中文))Display name, English (欄位對外名稱(英文))Example value (範例值)Field name, English (欄位名稱(英)) enameData format rule (限定資料格式)Required (必填)
Basic field (基本欄位)姓名Full name王小明nameLeave empty (built-in rule: only Chinese, English letters, digits, and _; no spaces)Yes
Custom field (自定義欄位)部門Department研發部department只能輸入中英文數字和_Yes
Custom field (自定義欄位)職稱Job title資深工程師position只能輸入中英文數字和_Yes
Custom field (自定義欄位)員工編號Employee IDA0001employee_id只允許輸入英數Yes

When you fill in the form:

  • Use one row for each field. The row order is the order of the fields on the credential.
  • The first row must be a required field. Its value shows in the bottom-left corner of the card face. The card face shows up to 18 characters in full. Characters after that are replaced with ”…”.
  • If a suitable basic field exists, use the basic field. Do not make a custom field for it. The names and rules of basic fields are fixed. See Basic fields. Only custom fields need a data format rule.
  • The field name, English (欄位名稱(英)) is the ename in the API. You suggest the ename of a custom field. The TCS team confirms it when it creates the credential type.
  • Each field needs both a Chinese and an English display name. A display name (Chinese or English) can contain Chinese, English letters, digits, or _. An ename can contain English letters, digits, or _.
  • A field value must match the rule of its field (the built-in rule of a basic field, or the data format rule that you selected for a custom field). If a value does not match, the API rejects the issuance with error code 10110.
  • In the API, every field value is a string. Boolean values are also text: true and false, or 0 and 1, depending on the format that you selected.
  • A required field must have a value. If a required field is missing, or its value is an empty string, the API rejects the issuance with error code 11001. If an optional field has no value, you can leave it out or send an empty string.
ChineseEnglishename
國民身分證統一編號National ID Numberid_number
民國出生年月日Date of Birth (Republic of China Era / ROC)roc_birthday
姓名Full namename
戶籍地址Permanent addressregistered_address
護照號碼Passport No.passport_no
居留證統一證號ARC Numberresidential_certificate_no
外來人口統一證號New UI No.UI_no
性別Gendergender
國籍Nationalitynationality
西元出生日期Date of Birth (YYYY/MM/DD)ad_birthday
汽(機)駕戶籍地址Registered Address (Driver)driver_registered_address
汽(機)駕戶籍區號Postal Codedriver_zip_no
汽(機)有效日License Expiration Datedriver_effect_date

Basic fields already have a built-in rule. You do not need to fill in a data format rule for them. The basic field 姓名 (name) accepts only Chinese, English letters, digits, and _. If the value contains a space, for example between the parts of an English name, the request is rejected with error code 10110. For a custom field, select one data format rule from this list. Each item shows the English meaning and then the admin UI label. The text in parentheses in the label is the rule that the admin UI shows.

  • Chinese only: 只能輸入中文
  • English letters only: 只允許輸入英文(只允許輸入大寫或小寫英文)
  • English letters and digits only: 只允許輸入英數(允許大寫字母、小寫字母以及數字)
  • English letters, digits, and _ only: 只能輸入英文數字和_
  • Chinese, English letters, digits, and _ only: 只能輸入中英文數字和_
  • These characters are not allowed: 不允許輸入 ~!@#$%^&*()_-+*/
  • URL format check: 網址格式檢查
  • Email format check: 電子郵件格式檢查
  • Taiwan mobile phone number (starts with 09, followed by 8 digits): 臺灣行動電話號碼規則(須以09開頭,後接8碼數字)
  • Taiwan national ID number: 台灣身分證字號
  • Passport number: 護照號碼
  • ARC number: 居留證統一證號
  • New UI number: 外來人口統一證號
  • Postal code (digits only, 3 digits): 郵遞區號(只允許輸入數字且長度為3碼)
  • Date of birth, Western calendar (digits only, 8 digits, format YYYYMMDD): 西元出生日期(只允許輸入數字且長度為8碼,日期格式 YYYYMMDD)
  • Date of birth, ROC calendar (for example 0991231, digits only, 7 digits): 民國出生年月日(0991231)(只允許輸入數字且長度為7碼)
  • Gender format check (1: male, 2: female): 性別格式檢查(1:男性 2:女性)
  • Nationality format check (0: domestic, 1: foreign): 國籍格式檢查(0:本國 1:外國)
  • String: 字串
  • Boolean (true, false): 布林值(true, false)
  • Boolean (0: false, 1: true): 布林值(0: false, 1: true)

If the rule that you need is not in this list, describe the rule in text. The TCS team evaluates whether it can add the rule.

The TCS team confirms these items with you when it creates the credential type: the maximum length of an ename, the maximum number of fields in one credential type, and the maximum length of a field value.

C. Verification scenario form (one form for each verification scenario)

Section titled “C. Verification scenario form (one form for each verification scenario)”

The item names are the names in the verification admin UI, which is in Chinese. Each item needs a Chinese version and an English version.

ItemDescriptionExample
VP name (VP 名稱)The name of this verification scenario. The wallet uses it as the title of the presentation screen.員工身分確認 (Employee identity check)
VP purpose of authorization (VP 授權目的)Why you ask the holder to present the data. You can use Chinese, English letters, and digits.確認來訪者是本公司員工 (Confirm that the visitor is an employee of our company)
Requested credential types and fields (要求出示的憑證類型與欄位)You can ask for credentials that other organizations issued, for example the driver’s license from the Highway Bureau. The TCS team confirms the maximum when it creates the verification scenario.範例公司員工證:姓名、員工編號 (Example Co. employee card: full name, employee ID)
VP authorization terms (VP 授權條款)The consent form that the wallet shows to the holder. Its text is the Ministry of Digital Affairs consent form template (數位憑證皮夾個人資料傳送同意書, the consent form for sending personal data from the wallet). Give the information for the 9 items in the table below. The TCS team writes the consent form from it.See the table below

Information for the VP authorization terms

ItemDescriptionExample
Name of the institution or organization (機構或組織名稱)The name of your organization, followed by 「(委託台灣圖靈鏈股份有限公司傳送資料)」 (“commissioned Turing Space Inc. to transmit the data”).範例股份有限公司(委託台灣圖靈鏈股份有限公司傳送資料) (Example Co., Ltd., commissioned Turing Space Inc. to transmit the data)
Privacy policy of the related service (相關服務之隱私權政策)The name and the URL of the privacy policy of your organization.範例股份有限公司隱私權政策 (Example Co. Privacy Policy), https://example.com/privacy
Name of the data collector (蒐集主體名稱)The same as above.範例股份有限公司(委託台灣圖靈鏈股份有限公司傳送資料) (Example Co., Ltd., commissioned Turing Space Inc. to transmit the data)
Purpose of collection (蒐集之目的)Why you collect this personal data.確認來訪者是本公司員工 (Confirm that the visitor is an employee of our company)
Categories of personal data (個人資料之類別)The categories of data that the holder presents. The wallet always sends 「憑證序號」 (the credential serial number), so the TCS team adds it.姓名、員工編號、憑證序號 (Full name, employee ID, credential serial number)
Period, area, users, and method of use of the personal data (個人資料利用之期間、地區、對象及方式)How long you keep the data after you receive it, where you use it, who uses it, and how you use it.驗證完成後 30 天;台灣;本公司人資部門;比對員工名冊 (30 days after the verification completes; Taiwan; our HR department; compare with the employee list)
Service name or name of the data collector (服務名稱或蒐集主體名稱)Whom the holder contacts to exercise their personal data rights. Enter your organization.範例股份有限公司 (Example Co., Ltd.)
Mailing address (收信地址)The address where the holder sends a personal data rights request.臺北市範例區範例路 1 號 (No. 1, Example Rd., Example Dist., Taipei City)
Recipient or department (收件人或部門)The recipient or department for a personal data rights request.人資部 個資窗口 (HR department, personal data contact)

On the presentation screen, the wallet shows 「提供資料的對象:台灣圖靈鏈股份有限公司」. On a phone set to English, it shows “Data will be shared with Turing Space”. The done screen says that the data was sent to 台灣圖靈鏈股份有限公司 (“You have authorized the data to be sent to Turing Space” in English). On these two screens, the wallet shows Turing Space Inc. as the party that receives the data. You cannot change this.

The data collector on the consent form is your organization, with the note that it commissioned Turing Space Inc. to transmit the data. Turing Space Inc., which the wallet screens show, is the party that transmits the data on your behalf. You decide how the data is used, and your organization handles requests from holders who exercise their personal data rights.