Skip to main content
RoadmapStatusChangelogStart Building Now

Overview

Unit's authentication mechanism relies on two types of API tokens - Org API tokens, used when making API calls from your server, and Customer API tokens, designed to be used directly from the customer's device.

Most API calls on Unit can be executed using an org api token, with the exception of certain card related actions (that are subject to PCI compliance requirements). For those actions, Unit requires that you use the customer token mechanism - as it keeps you out of the data flow, and prevents you from being subjected to PCI compliance requirements.

note

If you are PCI compliant, and want to manage sensitive card data yourself, please contact Unit.

The process of creating a customer token currently requires the end-customer to complete a two factor authentication facilitated by Unit.

If you are using an authentication provider that is PCI compliant and supports the JWT standard, you can rely on the authentication you already implemented to obtain a Unit customer token.

Currently Unit supports Auth0, Amazon Cognito and Stytch tokens. If you wish to use different standards or different authentication providers, please contact Unit.

Structure​

JSON Web Tokens consist of three parts separated by dots:

header.payload.signature

The payload contains a field called sub: The "sub" (subject) is the property that identifies the specific user the token belongs to and it is this part of the token that will be shared with Unit and associated with the unit Customer resource. When the user attempts to create a customer token using the JWT, we will use it to verify that the JWT belongs to that specific customer.

Read more about JWT here.

Obtaining a Customer Token using JWT​

To generate customer token using an existing JWT, follow these steps:

  1. Add the JWKs path to your Org. This is needed in order to allow Unit to verify the token. This setting is available on the Unit dashboard, under Settings > Org Settings > JWT Settings. More info can be found here or here.
    In case the issuer can be different from the one that can be inferred from the jwks path, add it also to the JWT Settings according to the authentication provider as described below so Unit will be able to validate the token issuer (the iss claim):
    When using Auth0 and Custom Domain is defined, set also Custom Domain field.
    When using Stytch and your Issuer is not in the following template: stytch.com/PROJECT_ID, please provide the correct one under the Issuer field.
  2. When creating an application, add the relevant JWT subject. You may also update / attach a JWT subject when updating a customer or when creating an application form (ApplicationFormPrefill)
  3. Create a customer token using the JWT token by calling the relevant API endpoint. This can be done by either prefilling an existing application form, creating an application or updating an existing customer:
  • Individual customer - 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. JWT subject may be attached to both the business contact and any of the authorized users.
note

In order to use the JWT to obtain a customer token, you must configure the authentication provider to enforce a two factor authentication requirement, and a 24h expiration.

Auth0​

  • You have to configure the Auth0 JWKs path on the Unit dashboard. This path should match the following format: https://<domain-name>.auth0.com/.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.

Stytch​

  • You have to configure the Stytch JWKs path on the Unit dashboard. This path should match the following format: https://[live|test].stytch.com/v1/sessions/jwks/<project-id>.
  • In case that the issuer is not in this format: stytch.com/<project-id> add it also to the JWT Settings. This will allow Unit to validate the token issuer.

Amazon Cognito​

  • You have to configure the Amazon Cognito JWKs path on the Unit dashboard. This path should match the following format: https://cognito-idp.<region>.amazonaws.com/<user-pool-id>/.well-known/jwks.json.