Get Token History by Reference ID

Returns a chronological list of token history records for the token identified by its tokenReferenceId.
Each entry contains the token state, associated card, device information, and timestamps.

URL test:

    https://test.lightcms.io/cms/v1/cards/tokens/reference/{tokenReferenceId}/history

Method:

GET

Path items:

/cards/tokens/reference/{tokenReferenceId}/history

Parameters:

Parameter	Location	Type	Example	Description	Required
tokenReferenceId	path	string	abcdef12345	Unique reference identifier of the token	Yes
page	query	integer	0	Zero‑based page index (default 0).	No
size	query	integer	20	Number of records per page (default 20).	No
sort	query	string	createdAt,desc	Sorting field and direction (e.g., createdAt,desc).	No
x-idempotency-key	header	string	1	Idempotency key – guarantees safe retries.	No
x-tenant	header	string	1	Tenant identifier (used in multi‑tenant deployments).	No

Example request:

    curl -X GET "https://test.lightcms.io/cms/v1/cards/tokens/reference/abcdef12345/history?page=0&size=20&sort=createdAt,desc" \
         -H 'accept: */*' \
         -H 'x-idempotency-key: 1' \
         -H 'x-tenant: 1'

Responses:

200 - OK

Status Code: 200 OK

[
  {
    "id": 4,
    "cardId": 116,
    "device": {
      "deviceId": "XX",
      "description": "44",
      "type": "44"
    },
    "cmsStatus": "ACTIVE",
    "cpStatus": "44",
    "tokenRequestor": {
      "code": "44",
      "description": "44"
    },
    "tokenUniqueReferenceId": "44",
    "panSource": "44",
    "tokenId": "44",
    "otp": {},
    "score": {
      "reasonCodes": []
    },
    "cvc2Match": false,
    "createdAt": "2025-07-21T16:09:24+02:00",
    "updatedAt": "2025-07-21T16:27:27+02:00"
  }
]

Parameter	Location	Type	Description
id		integer	Internal identifier of the token history record.
cardId		integer	CMS internal identifier of the card associated with this token version.
device.deviceId	device	string	Identifier of the device that enrolled the token.
device.description	device	string	Human‑readable description of the device.
device.type	device	string	Device type code.
cmsStatus		string	Current status of the token in the CMS (e.g., ACTIVE, INACTIVE).
cpStatus		string	Status of the token in the card‑processor system.
tokenRequestor.code	tokenRequestor	string	Code of the entity that requested the token (e.g., CUSTOMER, BANK).
tokenRequestor.description	tokenRequestor	string	Human‑readable description of the requestor.
tokenUniqueReferenceId		string	Unique reference linking the token to its originating request.
panSource		string	Source of the PAN for the token (e.g., ENCRYPTED, MASKED).
tokenId		string	Identifier of the token as returned by the processor.
otp		object	One‑time‑password related data (currently empty).
score.reasonCodes	score	array	List of reason codes influencing the token risk score.
cvc2Match		boolean	Indicates whether the CVC2 matches the stored value.
createdAt		string	ISO‑8601 timestamp when this token version was created.
updatedAt		string	ISO‑8601 timestamp of the most recent update to this token version.

404 - Not Found

Status Code: 404 Not Found

{
  "errorMessage": "Token history for reference ID abcdef12345 not found."
}

500 - Internal error

Status Code: 500 Internal error

{
  "timestamp": "2025-07-22T13:09:02.348+02:00",
  "status": 500,
  "error": "Internal Server Error",
  "path": "/cms/v2/cards/tokens/reference/abcdef12345/history"
}