Customer API 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.

When you create a new customer token that has access to sensitive scopes, a one-time password will be sent to the customer, and must be provided in the create customer token API call in order to create the token. A customer token is valid for up to 24 hours (customizable).

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.

How-To Guides

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"             }         }     }  }}'

Create Customer Token

Create a bearer token for a particular customer. The returned token can be used in the Authorization header as a secure alternative to the broader API token.

A Customer Token can only interact with resources under a particular customer. As an example, calling List Transactions with a customer bearer token will return only transactions within accounts under that particular customer.

note

When using a Customer Bearer Token, API calls may be made directly from your front-end (browser or app).

Verb	POST
Url	https://api.s.unit.sh/customers/:customerId/token
Required Scope	customer-token-write
Data Type	customerToken

Example Request (two-factor authentication not required):

curl -X POST 'https://api.s.unit.sh/customers/8/token'-H 'Content-Type: application/vnd.api+json'-H 'Authorization: Bearer ${TOKEN}'--data-raw '{  "data": {    "type": "customerToken",    "attributes": {      "scope": "customers accounts"    }  }}'

Attributes

Name	Type	Description
scope	string	list of Scopes separated by spaces.
verificationToken	string	Received as a response from Create Customer Token Verification. Required if scope includes a scope which require two-factor authentication.
verificationCode	string	6 digits code sent to the customer through the desired channel. Required if the scope attribute includes a scope which requires two-factor authentication.
expiresIn	integer	Optional. The lifetime of the token (in seconds). Maximum value is 86400 (24 hours). Default value is also 24 hours.

Listing all accounts of a customer:

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

Example Request (two-factor authentication required)

{  "data": {    "type": "customerToken",    "attributes": {      "scope": "customers accounts-write accounts",      "verificationToken": "i8FWKLBjXEg3TdeK93G3K9PKLzhbT6CRhn/VKkTsm....",      "verificationCode": "203130"    }  }}

Response

Response is a JSON:API document.

201 Created

Field	Type	Description
data.attributes.token	string	The token issued for the customer.
data.attributes.expiresIn	integer	The lifetime of the token (in seconds).

Example Response:

{  "data": {    "type": "customerBearerToken",    "attributes": {      "token": "v2.public.eyJyb2xlIjoiY3VzdG9tZX...",      "expiresIn": 86400    }  }}

Create Customer Token Verification

In order to increase security and prevent token theft, Unit supports two-factor authentication when creating a customer token.

When creating a customer token that contains a scope which requires two-factor authentication (see Scopes), it is required to first create a verification challenge that will be sent to the customer.

The challenge is a six digits code and is valid for 10 minutes after its creation.

note

The phone number that is used for the verification process is the one defined for the customer whose identifier is provided as part of the request params. An alternative phone number can be provided for Business Customers via the phone attribute (see below).

note

In Sandbox, a verification challenge message will read: 'Your Unit verification code is: XXXXXX'. In Production, 'Unit' will be replaced by your org's name.

Verb	POST
Url	https://api.s.unit.sh/customers/:customerId/token/verification
Required Scope	customers
Data Type	customerTokenVerification

Attributes

Name	Type	Description
channel	string	send a verification code to the customer through one of the following channels sms or call.
phone	Phone	Optional. For BusinessCustomer only, this allows providing the phone number of one of the customer's authorized users. The provided phone must match an authorized user phone and will be used in the One Time Password (OTP) authentication process instead of the business customer contact's phone.
appHash	string	Optional. For sms verifications only, 11-character hash string that identifies your app. Appended at the end of your verification SMS body the way that client-side SMS Retriever API expects.
language	"en" or "es"	Optional. Select the verification language. en - English, es - Spanish. Default is english

Create a token verification:

curl -X POST 'https://api.s.unit.sh/customers/10001/token/verification'-H 'Content-Type: application/vnd.api+json'-H 'Authorization: Bearer ${TOKEN}'--data-raw '{  "data": {    "type": "customerTokenVerification",    "attributes": {      "channel": "sms"    }  }}'

201 Created

Field	Type	Description
verificationToken	string	The generated verification token . It should be passed back to Create Customer Bearer Token along with the verification code the customer received on the specified channel

Example Response:

{  "data": {    "type": "customerTokenVerification",    "attributes": {      "verificationToken": "i8FWKLBjXEg3TdeK93G3K9PKLzhbT6CRhn/VKkTsm...."    }  }}