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. 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:
- Call create customer token verification
- You get a verification token in the response
- The customer receives a one time password
- The customer types the password into your UI
- 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.
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 |
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" } }}'
#
AttributesName | Type | Description |
---|---|---|
scope | string | list of Scopes separated by spaces. |
verificationToken | string | Required if scope includes a scope which require two-factor authentication. Received as a response from Create Customer Token Verification. |
verificationCode | string | Required if the scope attribute includes a scope which requires two-factor authentication. 6 digits code sent to the customer through the desired channel. |
expiresIn | integer | Optional. The lifetime of the token (in seconds). Maximum value is 86400 (24 hours). Default value is also 24 hours. |
curl -X GET 'https://api.s.unit.sh/accounts' \-H "Authorization: Bearer ${CUSTOMER_TOKEN}"
{ "data": { "type": "customerToken", "attributes": { "scope": "customers accounts-write accounts", "verificationToken": "i8FWKLBjXEg3TdeK93G3K9PKLzhbT6CRhn/VKkTsm....", "verificationCode": "203130" } }}
#
ResponseResponse is a JSON:API document.
#
201 CreatedField | Type | Description |
---|---|---|
data.attributes.token | string | The token issued for the customer. |
data.attributes.expiresIn | integer | The lifetime of the token (in seconds). |
{ "data": { "type": "customerBearerToken", "attributes": { "token": "v2.public.eyJyb2xlIjoiY3VzdG9tZX...", "expiresIn": 86400 } }}
note
Once created, it is recommended to store the cutomer token on the customer's device for further use. When using a Customer Token, API calls may be made directly from your front-end (browser or app).
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 Live, '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 |
#
AttributesName | 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 | string | Optional. Select the verification language using a 2-letters code. Default is English. See Localization Options bellow for the support languages and their 2-letters code. |
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 CreatedField | 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 |
#
Localization OptionsEnglish-en
, Afrikaans-af
, Arabic-ar
, Catalan-ca
, Chinese-zh
, Chinese (Mandarin)-zh-CN
, Chinese (Cantonese)-zh-HK
, Croatian-hr
, Czech-cs
, Danish-da
, Dutch-nl
, English (British)-en-GB
, Estonian-et
, Finnish-fi
, French-fr
, German-de
, Greek-el
, Hebrew-he
, Hindi-hi
, Hungarian-hu
, Indonesian-id
, Italian-it
, Japanese-ja
, Kannada-kn
, Korean-ko
, Malay-ms
, Marathi-mr
, Norwegian-nb
, Polish-pl
, Portuguese - Brazil-pt-BR
, Portuguese-pt
, Romanian-ro
, Russian-ru
, Slovak-sk
, Spanish-es
, Swedish-sv
, Tagalog-tl
, Telegu-te
, Thai-th
, Turkish-tr
, Vietnamese-vi
{ "data": { "type": "customerTokenVerification", "attributes": { "verificationToken": "i8FWKLBjXEg3TdeK93G3K9PKLzhbT6CRhn/VKkTsm...." } }}
Create Customer Token Using JWT#
Option to generate a customer token without Token Verification step.
info
For more information see the following guide
#
Prerequisites:- JWT public key should be available through the provider's JWKS endpoint.
- OrgSetting should contain JWKs path - Customizing the jwks path is done through the Unit Dashboard (under Org Settings > JWT Settings).. The supplied string should be in this format:
https://../.well-known/jwks.json
. - In case you have a custom domain defined add it also to the JWT Settings. This will allow Unit to validate the token issuer. The supplied string should be in this format:
https://../
without the.well-known/jwks.json
part. - Add JWT subject to the relevant Customer - can be done through ApplicationFormPrefill, Application creation or patch Customer:
Individual - must contain at least one: jwtSubject field or AuthorizedUser's jwtSubject field.
Business - must contain at least one: Contact's jwtSubject field or AuthorizedUser's jwtSubject field.
#
AttributesName | Type | Description |
---|---|---|
scope | string | list of Scopes separated by spaces. |
jwtToken | string | Required if scope includes a scope which require two-factor authentication. Should be in a valid JWT structure. |
note
At the moment only Auth0 JWTs are supported and RS256 is the only supported algorithm for signing.
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-write accounts", "jwtToken": "i8FW..." } }}'
#
ResponseSame as Create Customer Token response.
#
How-To GuidesBelow 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 cardsExample: Your application contains a page that displays the customer's debit cards.
Follow these steps:
- Call the Create customer token with the
cards
scope included. - Call the List Cards operation and pass the customer token received in step #1 in the request
Authorization
header. No need to pass thefilter[customerId]
parameter since the token handles the filtering.
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:
- The customer clicks the
Create Debit Card
button on their cards application page. - Call the Create Customer Token Verification. This will return a verification token and will send the customer a verification code.
- Allow the customer to enter the verification code they received.
- Call the Create customer token with the
cards-write
scope included as well as theverification token
received in step #2 and theverification code
entered by the customer in step #3. - Call the Create Individual Debit Card and pass the customer token received in step #4 in the request
Authorization
header.
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" } } } }}'