# Retrieve token details using query parameters

At least one of tokenId or namespace must be provided. If the token was created with a namespace, both tokenId and namespace must be supplied. To look up all tokens created under a namespace, query by namespace alone.

Endpoint: GET /tokens
Version: 3
Security: BasicAuth

## Query parameters:

  - `tokenId` (string)
    Worldpay's internal identifier for a token. If the token was created with a namespace, namespace must also be included as a query parameter.
    Example: "9925760692793807595"

  - `namespace` (string)
    A reference to group up to 16 tokens, e.g. for one customer. When queried by itself, all tokens under the namespace will be returned; when queried in combination with tokenId, a single token will be returned. Avoid personally identifiable information (PII) here to prevent the logging of sensitive identifiers.
    Example: "customer-1"

## Response 200 fields (application/vnd.worldpay.tokens-v3.hal+json):

  - `_embedded` (object, required)

  - `_embedded.tokens` (array, required)

  - `_embedded.tokens.tokenPaymentInstrument` (object)

  - `_embedded.tokens.tokenPaymentInstrument.type` (string)
    Indicating the type of this token.

  - `_embedded.tokens.tokenPaymentInstrument.href` (string)
    Link to the corresponding token.

  - `_embedded.tokens.tokenId` (string)
    Worldpay's internal identifier for a token. If supplied, must be between 15 and 21 characters, must consist of digits and upper-case characters excluding 'I' and 'O'.

  - `_embedded.tokens.description` (string)
    A description of your token. If not supplied, a default description is created for you.

  - `_embedded.tokens.tokenExpiryDateTime` (string)
    The date/time after which the token is unavailable, expressed in ISO 8601 format. If not supplied, the default expiry date/time is 90 days in Try and 4 years in the Live environment.We extend the expiry in Live by 4 years, if under half of the time remains on the token.

  - `_embedded.tokens.namespace` (string)
    A reference to group up to 16 cards, e.g. for one customer.

  - `_embedded.tokens.paymentInstrument` (object)

  - `_embedded.tokens.paymentInstrument.cardNumber` (string, required)

  - `_embedded.tokens.paymentInstrument.cardExpiryDate` (object, required)

  - `_embedded.tokens.paymentInstrument.cardExpiryDate.month` (integer, required)

  - `_embedded.tokens.paymentInstrument.cardExpiryDate.year` (integer, required)

  - `_embedded.tokens.paymentInstrument.type` (string)

  - `_embedded.tokens.paymentInstrument.cardHolderName` (string)
    The name on your customer's card.

  - `_embedded.tokens.paymentInstrument.bin` (string)

  - `_embedded.tokens.paymentInstrument.brand` (string)

  - `_embedded.tokens.paymentInstrument.fundingType` (string)

  - `_embedded.tokens.paymentInstrument.billingAddress` (object)

  - `_embedded.tokens.paymentInstrument.billingAddress.address1` (string, required)

  - `_embedded.tokens.paymentInstrument.billingAddress.postalCode` (string, required)

  - `_embedded.tokens.paymentInstrument.billingAddress.city` (string, required)

  - `_embedded.tokens.paymentInstrument.billingAddress.countryCode` (string, required)

  - `_embedded.tokens.paymentInstrument.billingAddress.address2` (string)

  - `_embedded.tokens.paymentInstrument.billingAddress.address3` (string)

  - `_embedded.tokens.paymentInstrument.billingAddress.state` (string)

  - `_embedded.tokens.paymentInstrument.networkType` (string)

  - `_embedded.tokens.paymentInstrument.last4Digits` (string)

  - `_embedded.tokens.schemeTransactionReference` (string)
    A value provided by Visa or Mastercard which tracks recurring transactions.Note: You are not normally expected to provide a value for schemeTransactionReference. If you are using the [Verified Tokens API](/products/verified-tokens/@v3/index.md) to create tokens, it is automatically included where applicable.

  - `_embedded.tokens._links` (object, required)

  - `_links` (object, required)

## Response 405 fields (application/vnd.worldpay.tokens-v3.hal+json):

  - `errorName` (string)
    Example: "methodNotAllowed"

  - `message` (string)
    Example: "Requested method is not allowed"

## Response 500 fields (application/vnd.worldpay.tokens-v3.hal+json):

  - `errorName` (string)
    Example: "tokenizationNotEnabled"

  - `message` (string)
    Example: "Tokenization not enabled"