Authentication overview

The API has two layers of authentication:

1. Account authentication identifies and authenticates requests from your app. All API requests and UI components require account authentication.

2. End-user authentication identifies the end-user (root userRoot user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity must always have one root user. or authorised user) acting through your app. Almost all API requests and UI components require it. The user proves their identity at login and receives an Auth Token. The operations available depend on the user's assigned role.

Operations covered by Strong Customer Authentication under PSD2 - including viewing sensitive card details, creating authorised usersAuthorised Users Individuals that have been invited by the root user to manage an identity's instruments and transactions. They are not the legal owners of the identity but can be granted access to perform operations on behalf of the identity. For corporates, card assignees are created as Authorised Users., and reading older statements - also require the end-user token to be stepped up. Step-up is the same end-user authentication after the user clears a second factor (SMS OTP or biometrics); it produces a stepped-up Auth Token that unlocks the gated endpoints. See Step-up authentication for the full list of gated endpoints and UI components and how to perform one.

Depending on the operation, you must provide:

• account authentication only,
• account and end-user authentication via an Auth Token, or
• account and a stepped-up end-user Auth Token.

Exchanging an auth token for an access token

If you support any of the access token use cases, your program needs to handle both auth tokens and access tokens.

auth_token field naming

In our API documentation, we refer to auth_token. If you are configured for any of the Root usersRoot user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity must always have one root user. linked to multiple identities or Biometrics use cases, the field carries an access token rather than an auth token-the field name is unchanged for backward compatibility.

After completing a successful login, an Auth Token is provided. This token contains information that identifies the user and the method of authentication (password, passcode, biometrics). The Auth Token unlocks very limited functionality.

In order to grant access to the correct identity, the Auth Token needs to be exchanged for an Access Token. The Access Token contains the information that was missing from the Auth Token, namely the identity that the user would like to access.

Single login across multiple corporates

Single login accessing multiple CorporatesCorporates Business entities that can be onboarded as identities on Weavr. Corporate identities represent companies and require Know Your Business (KYB) verification. They can have multiple authorised users and issue cards to card assignees. is an optional feature when you deal with Corporate users. Once activated, an individual end user (root userRoot user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity must always have one root user.) can be granted access to multiple CorporatesCorporates Business entities that can be onboarded as identities on Weavr. Corporate identities represent companies and require Know Your Business (KYB) verification. They can have multiple authorised users and issue cards to card assignees. through one primary email and password login, so they can switch back and forth between CorporatesCorporates Business entities that can be onboarded as identities on Weavr. Corporate identities represent companies and require Know Your Business (KYB) verification. They can have multiple authorised users and issue cards to card assignees. without having to log out and log back in with a different email and password. To activate this feature, contact us.

SDK capability matrix

Some authentication factors and secure components are mobile-only. Use the following matrix when planning your auth and instrumentInstrument A financial product owned by an Identity. There are two types: Managed Accounts (stored-value accounts that hold balances and can receive wire transfers) and Managed Cards (prepaid cards - virtual or physical - used for purchases). flows so the architecture matches what each platform can actually deliver.

Capability	Web SDK	iOS / Android / React Native SDKs
Password login	✓	✓
Passcode login	✓	✓
Biometric login		✓
Step-up via SMS OTP	✓	✓
Step-up via push notification		✓
Step-up via biometrics		✓ ¹
Push provisioningPush Provisioning A method that allows cardholders to add their card to a digital wallet (such as Apple Pay or Google Pay) directly from your app. The card details are securely tokenized and sent to the wallet provider, streamlining the process and enhancing the user experience compared to manual provisioning. This feature is currently in beta. (Apple Pay / Google Pay)		✓
Secure card display (PANPAN Primary Account Number - the long card number (typically 16 digits) printed or embossed on a payment card and used to identify the card on the payment network. Weavr never returns the raw PAN to your client; `GET /managed_cards/{id}` returns the PAN in tokenized form as `cardNumber`, and the value is only detokenized inside a Secure UI card-number component (a sandboxed iframe on the web, a secure native view on mobile)., CVVCVV Card Verification Value - the 3-digit security code printed on a payment card, used to authenticate card-not-present transactions. Weavr returns CVV in tokenized form on `GET /managed_cards/{id}` (with a stepped-up token); the value is only detokenized inside the SDK's secure CVV display component., PINPIN Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component.)	✓	✓
KYCKYC Know Your Customer - the identity verification process for consumer identities. This process allows you to seamlessly and securely verify your user's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. / KYBKYB Know Your Business - the identity verification process for corporate identities. This process allows you to seamlessly and securely verify your business customer's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. secure components	✓	✓

¹ Step-up via biometrics requires the user's mobile device to be enrolled for biometrics first - device enrolment is itself a mobile-only operation. See Step-up via biometrics.