Authentication and customer token

Most of Unit's components rely on customer tokens as an authentication method. For authorization (permissions differentiation), Unit uses Scopes inside the token. Each component will require different scope, and the customer token should be created with the correct ones. Scopes are divided into two types: those that require two-factor authentication (2FA) and those that do not. Each component can either perform 2FA by SMS independently or rely on the 2FA performed by your application. In this section, we will cover how to create a customer token and how to use it with different flows with White-Label UIs.

Two-factor authentication as a part of component experience

If you prefer 2FA flow to be a part of the component experience, you can create a customer token with an upgradableScope. In this case scope should always contain the customer-token-write scope. Upgradable scope will allow the component to perform 2FA for the customer, without the need for your application to perform 2FA.

For example if you are using unit-elements-card which requires customers cards cards-sensitive cards-sensitive-write cards-write, your request should contain customers cards customer-token-write scope and cards-sensitive-write cards-write in upgradable scope.

For individual customers, an SMS will be sent to the customer's phone number. For business customers, the SMS will be sent to the phone number of the business contact by default, or to the phone number of the authorized user if provided.

caution

White-label UIs will use the localStorage key unitVerifiedCustomerToken. It's important to clean it up when the user logs out from your app.

localStorage.removeItem('unitVerifiedCustomerToken');

Create Customer Token request a customer (component will perform 2FA and send an SMS to the customer)

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

Attributes

Name	Type	Description
scope	string	list of Scopes separated by spaces.
upgradableScope	string	Required. list of Scopes separated by spaces. The customer will be able to upgrade the token to the scopes you provide here. customer-token-write scope is required when setting this attribute.

Create Customer Token request for an authorized user (component will perform 2FA and send an SMS to the authorized user)

curl -X POST 'https://api.s.unit.sh/customers/${id}/token' \
--H 'Content-Type: application/vnd.api+json' \
--H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data": {
    "type": "customerToken",
    "attributes": {
      "scope": "customers cards customer-token-write",
      "upgradableScope": "cards-sensitive-write cards-write"
    },
    "relationships": {
      "authorizedUserResource": {
        "data":
        {
          "type": "authorizedUserResource",
          "id": "10001"
        }
      }
    }
  }
}'

Attributes

Name	Type	Description
scope	string	list of Scopes separated by spaces.
upgradableScope	string	Optional. list of Scopes separated by spaces. The customer will be able to upgrade the token to the scopes you provide here. customer-token-write scope is required when setting this attribute.

Relationships

Name	Type	Description
authorizedUserResource	JSON:API Relationship	The Authorized User id to whom the SMS will be sent