API Tokens

Customer Tokens

Create a Customer Token to access customer specific data or execute sensitive actions (related to funds movement). Customer Tokens only allow access to resources that are associated with the specific customer the token was created for. A customer token is valid for up to 24 hours (customizable by setting the expiresIn field).

In order to create a new customer token that has access to sensitive scopes, the customer must be taken through two factor authentication (one-time password) or to supply Json Web Token (See this section for more information.). The flow of API calls will be:

1. Call create customer token verification.
2. Receive a verification token in the response
3. The customer receives a one time password
4. The customer types the password into your UI
5. Call create customer token and provide the verificationToken you received in step #2 and verificationCode you received in step #4. You receive a new customer token in response.

In order to avoid repeat customer authentications, you may store the customer token and re-use it until it expires. The recommended way to store the customer token is on the customer's device, using the browser's local storage.

info

It is advisable that you read and understand the recommended way to use Unit's Authentication and Scopes before you create and use API tokens in your app.

Testing Customer Tokens

In Sandbox, Unit will not send a text message, in order to avoid breaching the electronic communications consent requirements. In order to create a customer token that has access to scopes that require two factor authentication, please use the passcode 000001.

Use Cases

Below are common use cases for using a customer token and steps you’ll need to follow to build them:

Allowing a customer to view their debit cards

Example: Your application contains a page that displays the customer's debit cards.

Follow these steps:

1. Call the Create customer token with the cards scope included.
2. Call the List Cards operation and pass the customer token received in step #1 in the request Authorization header. No need to pass the filter[customerId] parameter since the token handles the filtering.

Listing all cards of a customer example:

curl -X GET 'https://api.s.unit.sh/cards' \
-H "Authorization: Bearer ${CUSTOMER_TOKEN}"

Allowing a customer to create a new debit card (requires two-factor authentication)

Example: Your application contains a page that enables debit card creation.

Follow these steps:

1. The customer clicks the Create Debit Card button on their cards application page.
2. Call the Create Customer Token Verification. This will return a verification token and will send the customer a verification code.
3. Allow the customer to enter the verification code they received.
4. Call the Create customer token with the cards-write scope included as well as the verification token received in step #2 and the verification code entered by the customer in step #3.
5. Call the Create Individual Debit Card and pass the customer token received in step #4 in the request Authorization header.

Creating a new debit card example:

curl -X POST 'https://api.s.unit.sh/cards' \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer ${CUSTOMER_TOKEN}" \
--data-raw '{
  "data":{
    "type":"individualDebitCard",
     "attributes": {
         "shippingAddress": {
             "street": "5230 Newell Rd",
             "city": "Palo Alto",
             "state": "CA",
             "postalCode": "94303",
             "country": "US"
         }
     },
     "relationships": {
         "account": {
             "data": {
                 "type": "depositAccount",
                 "id": "10001"
             }
         }
     }
  }
}
'