Skip to content

Revoke API

You revoke a credential through TCS API for DIW with the cid that you got at issuance. In our tests, within about one minute after revocation, the holder’s Taiwan Digital Identity Wallet (TW DIW, “the wallet” in this handbook) shows this credential as invalid (「已失效」, or “Expired” when the phone language is English). You cannot undo a revocation.

Rendering diagram...
POST /v1/diw/credentials/{cid}/revoke

In {cid}, put the cid that you got when GET /v1/diw/issuances/{id} returned issued. Use the full value unchanged. This request has no body.

Every request must include X-API-Key. Also include x-correlation-id, and put the same value in x-request-id. See API Basics.

On success, you get 201:

{
"cid": "<cid>",
"credential_status": "REVOKED"
}
FieldDescription
cidThe same cid that you sent in the revoke request.
credential_statusThe status after revocation: REVOKED.

The API currently cannot suspend or recover a credential.

Only the account that received this cid can revoke it. If a different account sends the same cid, that account gets 404.

When you get 502, TCS cannot confirm whether the revocation took effect. Send the same request again:

  • You get 201: the revocation is complete.
  • You get 400 and the message starts with issuer module 30205: the credential is already revoked. This means that the first revocation succeeded.
  • You get 400 and the message starts with issuer module, but the code is not 30205: do not treat this as a successful first revocation. Contact the TCS team with the time and the x-correlation-id of both requests.
  • You get 502 again: resend later. If you keep getting 502, contact the TCS team with the time and the x-correlation-id of each request.

If you cannot tell whether the first request succeeded, contact the TCS team with the time and the x-correlation-id / x-request-id value of both requests.

For other errors, see Errors and Polling.

What you see when you verify after revocation

Section titled “What you see when you verify after revocation”

After revocation, the wallet does not let the holder present this credential. A revoked credential does not appear in verification results.

After you create a verification, one of these three cases occurs:

Credentials of the same credential type in the holder’s walletThe result you get
Only the revoked credentialThe wallet does not let the holder select this credential, so the wallet sends no data. The status stays pending (waiting) for the full timeout that you set.
Another valid credential, tooThe holder presents the other credential. The verification passes (verify_result: true), but data[].cid is the cid of the other credential.
The credential you expect is not revokedYou get a verification result. Use verify_result to decide whether it passed, and still compare data[].cid.

Wallet presentation screen: the data is provided to Turing Space Inc., the credential area says that no credential can be authorized, and the send data button is disabled.

The first case in the table: the wallet says that no credential can be authorized (目前缺少可授權的憑證), and the holder cannot tap the send data button. The screen is in Chinese.

Checking only verify_result is not enough. Your system must also do two things:

  1. Compare the cid. Accept the result only if data[].cid equals the credential_serial that you stored. If you do not, you may mistake another credential that the holder presents for the credential that you revoked.

    data[].cid must equal the credential_serial that you stored at issuance. See Verification API.

  2. Set your own timeout. If the verification stays pending, end this verification when the time is up (the recommended value is 5 minutes). Tell the holder that you did not receive a usable credential. If you do not, a holder who has only the revoked credential stays on the waiting screen indefinitely.

For a diagram of the flow, see How It Works.