# Get tokens

The GET /tokens endpoint retrieves a list of all tokens for the authenticated member.

Endpoint: GET /tokens
Security: Bearer, BasicAuth

## Query parameters:

  - `type` (string)
    Specifies the type of token returned.
    Enum: "INVALID", "ACCESS", "TRANSFER"

  - `page.offset` (string)
    The offset for the current page. If the offset has been provided in the request, this offset will be equal to the provided one. But if no offset was provided in the request (i.e. this is the first page) and the page is not empty, this field will be populated with a non-empty string. This may be helpful for loading the same page again, which might not always be possible with an empty offset due to a dynamic nature of the data. The offset is not visible to a user and should not be parsed and/or understood in any way.
    Example: "LerV6Jmex"

  - `page.limit` (integer, required)
    The maximum number of records to return. This must be less than 200.
    Example: 175

  - `filter.sourceAccountId` (string)
    Identifies the payer's account.
    Example: "a:J72REftaRoiaDYRDU7M9FDgf8jeh3eqek9DvKeyBWbuA:3VMczyq7r7b6HwC"

  - `filter.destinationAccountId` (string)
    Identifies the payee/beneficiary's account.
    Example: "a:f34VSeqwfWGTGH23vsa2cDgecew209jdvcd5vdfv4vds:5VSWVRqicm4Csa2"

  - `filter.startTimeMs` (string)
    The filtered list start timestamp in milliseconds, 1 day (24 hours) = 8640000000, 1 hour = 36000000, and 1 minute = 60000.
    Example: 67505

  - `filter.endTimeMs` (string)
    The filtered list end timestamp in milliseconds, 1 day (24 hours) = 8640000000, 1 hour = 36000000, and 1 minute = 60000.
    Example: 365650

  - `filter.role` (string)
    Filters by accountHolder role.
    Enum: "ANY", "FROM", "TO", "ISSUER"

  - `filter.actingAsRefId` (string)
    Filters the list by the sub-TPP identifier generated by Token.io once a TPP has been onboarded.
    Example: "4kwl35c9sp3fwp4xq"

## Response 200 fields (application/json):

  - `offset` (string)
    The offset of the first item returned in the collection.
    Example: "LerV6Jmex"

  - `tokens` (array)
    Contains the details of each requested token returned according to the request's filtering parameters.

  - `tokens.id` (string)
    Identifies a unique authorization token for a transfer, standing order, or account information access.
    Example: "ta:3eYPU1BEKKunfmYgQuSKXFCeo851C5Y3XiZW3XA465TU:5zKtXEAq"

  - `tokens.payload` (object)
    Contains the details about the token specified by id.

  - `tokens.payload.actingAs` (object)
    Specifies another party for whom the token was created 'on behalf of'.

  - `tokens.payload.actingAs.displayName` (string)
    The name of the recipient shown to the user; required when specifying actingAs, optional otherwise.
    Example: "The Great Baking Co."

  - `tokens.payload.actingAs.refId` (string)
    The TPP-generated reference identifier for the token. This is not to be confused with the requestId. The refId maps to the tppRefId in the bank's consentRequest. This is needed to match/verify the originating token request with the bank's consent request. We recommend that the refId should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-'). This field should not exceed 18 characters in length.
    Example: "9htio4a1sp2akdr1aa"

  - `tokens.payload.actingAs.secondaryName` (string)
    The domain or email address of the recipient shown to the user along with the displayName.
    Example: "jane.doe@company.com"

  - `tokens.payload.authorizationMetadata` (object)
    Bank-defined additional authorization properties.

  - `tokens.payload.description` (string)
    Description of the payment with the following qualifiersmust not contain special characters length must be no greater than 255 charactersthe description in a subsequent call must match description in originating requestthe description omitted in originating request must also be omitted in subsequent callsthe description omitted in subsequent call will be replaced with refId, this field maps to the description in the bank's consentRequest presented to the user.Warning - If the description in a subsequent token request for lookups/changes/updates (retrieve, redeem, or cancel) doesn't match the description in the originating token request, an exception is thrown.
    Example: "This describes the payment."

  - `tokens.payload.effectiveAtMs` (string)
    Sets when the token took effect in milliseconds, 1 day (24 hours) = 8640000000, 1 hour = 36000000, and 1 minute = 60000
    Example: "1523514000"

  - `tokens.payload.endorseUntilMs` (string)
    The token can be endorsed until this time in milliseconds, 1 day (24 hours) = 8640000000, 1 hour = 36000000, and 1 minute = 60000
    Example: "254800000"

  - `tokens.payload.expiresAtMs` (string)
    Token expiration date-time. Access tokens typically have a 90-day lifespan unless overridden by tokenExpiration in the original token request. For transfer tokens, this is a bank-optional expiration time. Note - Not all banks support the override of the 90-day default
    Example: "29671679919284586"

  - `tokens.payload.from` (object)
    Contains information identifying the Token.io member.

  - `tokens.payload.from.alias` (object)
    Alternate or additional member identification information.

  - `tokens.payload.from.alias.realmId` (string)
    Identifies a member created under the realm of a specific bank.
    Example: "m:vHZUAMFt6s64vn6aDyMiwBYbPDN:5zKtXEAq"

  - `tokens.payload.from.alias.type` (string)
    The types of alias available.
    Enum: "INVALID", "UNKNOWN", "EMAIL", "PHONE", "DOMAIN", "BANK", "CUSTOM", "EIDAS"

  - `tokens.payload.from.alias.value` (string)
    The alias string representing the type.
    Example: "e-sales@token.io"

  - `tokens.payload.from.id` (string, required)
    The Token.io-assigned memberId of the TPP.
    Example: "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq"

  - `tokens.payload.initiatorId` (string)
    The memberId of the member that requested the token creation.
    Example: "m:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq"

  - `tokens.payload.issuer` (object)
    Contains information identifying the Token.io member.

  - `tokens.payload.issuer.alias` (object)
    Alternate or additional member identification information.

  - `tokens.payload.issuer.alias.realmId` (string)
    Identifies a member created under the realm of a specific bank.
    Example: "m:vHZUAMFt6s64vn6aDyMiwBYbPDN:5zKtXEAq"

  - `tokens.payload.issuer.alias.type` (string)
    The types of alias available.
    Enum: "INVALID", "UNKNOWN", "EMAIL", "PHONE", "DOMAIN", "BANK", "CUSTOM", "EIDAS"

  - `tokens.payload.issuer.alias.value` (string)
    The alias string representing the type.
    Example: "e-sales@token.io"

  - `tokens.payload.issuer.id` (string, required)
    The Token.io-assigned memberId of the TPP.
    Example: "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq"

  - `tokens.payload.receiptRequested` (boolean)
    Indicates whether the TPP requested an email confirmation of the token request be sent to the user.

  - `tokens.payload.refId` (string)
    The TPP-generated reference identifier for the token. This is not to be confused with the requestId. The refId maps to the tppRefId in the bank's consentRequest. This is needed to match/verify the originating token request with the bank's consent request. We recommend that the refId should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-'). This field should not exceed 18 characters in length.
    Example: "9htio4a1sp2akdr1aa"

  - `tokens.payload.to` (object)
    Contains information identifying the Token.io member.

  - `tokens.payload.to.alias` (object)
    Alternate or additional member identification information.

  - `tokens.payload.to.alias.realmId` (string)
    Identifies a member created under the realm of a specific bank.
    Example: "m:vHZUAMFt6s64vn6aDyMiwBYbPDN:5zKtXEAq"

  - `tokens.payload.to.alias.type` (string)
    The types of alias available.
    Enum: "INVALID", "UNKNOWN", "EMAIL", "PHONE", "DOMAIN", "BANK", "CUSTOM", "EIDAS"

  - `tokens.payload.to.alias.value` (string)
    The alias string representing the type.
    Example: "e-sales@token.io"

  - `tokens.payload.to.id` (string, required)
    The Token.io-assigned memberId of the TPP.
    Example: "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq"

  - `tokens.payload.tokenRequestId` (string)
    Identifies the original token request. The value returned in the response to the original token request as the id.
    Example: "rq:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq"

  - `tokens.payload.version` (string)
    Token.io API version number
    Example: "1.0"

  - `tokens.payloadSignatures` (array)
    Contains information about the payload signatures.

  - `tokens.payloadSignatures.action` (string)
    Specifies the signature validation action.
    Enum: "INVALID", "ENDORSED", "CANCELED"

  - `tokens.payloadSignatures.signature` (object)
    Contains information about the signing party. This is only present if a tokenId is present. It can be used to validate that the provided tokenId corresponds to the token request (this is needed for the Hosted Pages flows only).

  - `tokens.payloadSignatures.signature.keyId` (string)
    The id of the public key used to verify the signature. This is only present if a tokenId is present. It can be used to validate that the provided tokenId corresponds to the token request (this is needed for Hosted Pages flows only).
    Example: "CqSTHPvWY_dgVh-f"

  - `tokens.payloadSignatures.signature.memberId` (string)
    The Token.io member id of the signing member.
    Example: "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq"

  - `tokens.payloadSignatures.signature.signature` (string)
    The Base64url-encoded ciphertext signature.
    Example: "ODRWmM0xMRM7CKmK3bNl4e2Kb2btavTbZssCsrHsu8yopoKxBzouBrD9q5-E63tgdV1DpB7i31vwNDKywA0CAE"

  - `tokens.replacedByTokenId` (string)
    The id of the latest token replacing the original tokenId.
    Example: "ta:BzFCFwVt5zrt6rdcHJK5imf2HXbGdVdyHKpWQZbgzL5s:qXTkpBAZVbXMxk9vi"

  - `tokens.tokenRequestId` (string)
    Identifies the original token request.
    Example: "rq:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq"

## Response 400 fields (application/json):

  - `error` (object)
    The request does not have valid authentication credentials needed to perform the operation.

  - `error.message` (string)
    A description of the error.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 401 fields (application/json):

  - `error` (object)
    The request does not have valid authentication credentials needed to perform the operation.

  - `error.message` (string)
    A description of the error.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 403 fields (application/json):

  - `error` (object, required)
    The error returned when the member is not authorized to perform the given operation: PermissionDenied. This error message will be accompanied by the reason from the bank. Typically this means the access token has expired and the user must re-authenticate with the bank.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 404 fields (application/json):

  - `error` (object, required)
    The error object returned when given payment cannot be found: ResourceNotFound.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.paymentId` (string, required)
    The requested entity, the paymentID, was not found.
    Example: "pm2:12345abcd:abcde"

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 429 fields (application/json):

  - `error` (object, required)
    Resource exhausted. Too many requests.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.paymentId` (string, required)
    The maximum number of requests has been reached.
    Example: "Resource exhausted. Check quota."

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 500 fields (application/json):

  - `error` (object)
    This could refer to either an error by the payment service provider or the bank. When the bank reports a 5xx error, "token-external-error": "true" is set as a header in the HTTP response, indicating that the "internal" error originates from the bank. When one of the payment service providers internal services fails or when the bank reports a 4xx error, this header is not populated. The absence of this response header should be interpreted as "token-external-error": "false".

  - `error.errorCode` (string, required)
    This is a textual error code categorising the error.
    Example: "InternalServerError"

  - `error.message` (string, required)
    A description of the error.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 501 fields (application/json):

  - `error` (object, required)
    The operation was not implemented, supported or enabled by the bank.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.paymentId` (string, required)
    The operation was not implemented,supported or enabled by the bank.
    Example: "Not implemented."

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 503 fields (application/json):

  - `error` (object, required)
    Service is unavailable, likely due to a transient condition; this is usually corrected with a retry.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.paymentId` (string, required)
    The service is unavailable, likely due to a transient condition; this is usually corrected with a retry.
    Example: "Unavailable"

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 504 fields (application/json):

  - `error` (object, required)
    The deadline expired before the operation could complete.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.paymentId` (string, required)
    The deadline expired before the operation could complete.
    Example: "Deadline exceeded."

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"