Client Tokens

Overview

info

Most client tokens are valid for 10 minutes. Once expired, you must generate a new one.

Client tokens are short-lived credentials that pass sensitive information from your client to Highnote. Some use cases require client tokens; some are recommended to use them for enhanced security. Client tokens are valid for 10 minutes. When a token expires, you must generate a new one.

Generating client tokens requires an API key. The token generation mutation should be done from your server and sent to your client.

To use client tokens:

1. Generate a client token scoped to your use case.
2. Set your authorization header.
3. Call the API with the client token in the authorization header.

Supported use cases

The following use cases are supported for client tokens:

Use Case	Generate Token	Utilize Token	Requires Token
Card Viewer SDK	Generate token	Utilize token	Yes
Secure Inputs SDK for PINs	Generate token	Utilize token	Yes
Tokenize business account holder	Generate token	Utilize token	Yes
Tokenize person account holder	Generate token	Utilize token	Yes
Tokenize authorized user	Generate token	Utilize token	Yes
Create business account holder	Generate token	Utilize token	No
Create person account holder	Generate token	Utilize token	No
Create authorized user	Generate token	Utilize token	No
Create document upload session	Generate token	Utilize token	No
Set payment card PIN	Generate token	Utilize token	Yes
View account and routing number	Generate token		Yes
View payment card details	Generate token		Yes
View external bank account details	Generate token		Yes

Generate a client token

Every client token has a unique mutation associated with it. These mutations use the ID of the object you are tokenizing and requested permissions as inputs.

The following mutation example generates a payment card client token to set a PIN on a payment card. Refer to the supported use cases reference for the mutation for your use case.

GeneratePaymentCardClientToken

Query

mutation GeneratePaymentCardClientToken(
  $input: GeneratePaymentCardClientTokenInput!
) {
  generatePaymentCardClientToken(input: $input) {
    ... on ClientToken {
      value
      expirationDate
    }
  }
}

Variables

{
  "input": {
    "paymentCardId": "PAYMENT_CARD_ID",
    "permissions": [
      "SET_PAYMENT_CARD_PIN"
    ]
  }
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "generatePaymentCardClientToken": {
      "value": "TOKEN",
      "expirationDate": "2022-02-07T20:04:50.633Z"
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

Set authorization header

Once you have generated a client token, you must set the authorization header in your GraphQL client with the token.

The following example shows the base64 encoded client token that we generated using the GeneratePaymentCardClientToken mutation, and the example authorization header for our use case:

Example client token

eyJraWQiOiIxIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJhdWQiOiJwcm9kLnRlc3QuYXBpLmJheTEuY29tIiwib3JnIjoib2dfYnMwMWQ3ODNhY2U5NzBiZjRiMGE5ZDQxNGNmNzRjMzIyZjZkIiwicmVnIjoiVVNBIiwiYXBwaWQiOiJhcF9iYXkxOmNsaWVudHNkazowMDAwMDAwMDAwMDAwMDAwMCIsImlzcyI6InByb2QuYXV0aC5iYXkxLmNvbSIsInJ0X2FjY291bnRfaG9sZGVyX3Rva2VuaXplX3ciOltdLCJ0biI6InRuXzIzdXN0M3ByM2FlOGRmODE1NDdkNGM3MDhjZjVmYTI2YzJkZGVjNDUiLCJleHAiOjE2NDIwMTUzNzksImVudiI6InRlc3QiLCJpYXQiOjE2NDIwMTQ0Nzl9

Example authorization header

curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <base64_encoded_client_token>' \
--data '{"query":"mutation SetPinForPaymentCard($input: SetPinForPaymentCardInput!) {\n  setPinForPaymentCard(input: $input) {\n    __typename\n    ...on PaymentCard {\n      id\n      bin\n      last4\n    }\n    ... on UserError {\n        errors {\n          path\n          code\n        }\n      }\n    }\n}", "variables": {"input":"{\n\t\"paymentCardId\": \"some-payment-card-id\",\n\t\"newPin\": \"12ssss34\"\n}"}}' \
https://api.us.test.highnote.com/graphql

Call the API

After setting the authorization header, you can call the API.

The following example uses the SetPinForPaymentCard mutation to call the API and set the PIN for the payment card:

SetPinForPaymentCard

Query

mutation SetPinForPaymentCard($input: SetPinForPaymentCardInput!) {
  setPinForPaymentCard(input: $input) {
    __typename
    ... on PaymentCard {
      id
    }
    ... on UserError {
      errors {
        errorPath
        code
      }
    }
  }
}

Variables

{
  "input": {
    "paymentCardId": "PAYMENT_CARD_ID",
    "newPin": "1234"
  }
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "setPinForPaymentCard": {
      "__typename": "PaymentCard",
      "id": "PAYMENT_CARD_ID"
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}