Authenticate API calls on behalf of your customers

When acting for a customer or their user, you need to authenticate that endpoint with an additional token that verifies their customer and consent.

API key required on every request

Your backend needs an EmbedderEmbedder (Embedded Finance Provider). A company or developer that integrates Weavr's embedded finance services into their own application to provide financial services to their end customers. API key for every request. See Authenticate as an Embedder for key setup and safe handling.

Access Tokens

To call an API endpoint on behalf of a customer, send your EmbedderEmbedder (Embedded Finance Provider). A company or developer that integrates Weavr's embedded finance services into their own application to provide financial services to their end customers. API key and the customer's customer-scoped Access Token. The Access Token identifies the user and the selected customer, and determines the operations they can perform through their role.

Get an Access Token by verifying the user acting through your app with their Weavr credentials. If the user can act for more than one customer, have them select one before you request the Access Token.

Customers and your app's users

A customer in the Weavr platform is separate from the account a customer signs in to in your own app. The customer is the regulated record that holds accounts, cards, and payment permissions, and the end user authenticates against it directly - Strong Customer Authentication can't be delegated to your app. Even so, your customer should experience a single app and a single set of credentials. See Customers and your app's users for how the two relate.

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

To authenticate an end-user API request, provide your EmbedderEmbedder (Embedded Finance Provider). A company or developer that integrates Weavr's embedded finance services into their own application to provide financial services to their end customers. API key and one of the following:

• an Access Token, or
• a stepped-up Access Token for an SCASCA (Strong Customer Authentication). Strong Customer Authentication - a two-factor authentication solution required by PSD2 regulations for when end-users are accessing their payment account sensitive information or initiating transactions. SCA requires at least two of the following: something you know (password), something you have (device), or something you are (biometrics).-protected operation.

From user verification to customer access

One corporate user has one set of credentials and can act for one or more corporate identities. The verification response tells your app whether Weavr could select the customer automatically:

• tokenType: ACCESS means the user has one active customer. The returned token is already scoped to it and can be used for customer operations.
• tokenType: AUTH means the user has more than one active customer. Use the token to retrieve their identities, let them select one, then exchange it for an customer-scoped Access Token.

Always inspect tokenType. An integration that assumes verification always returns an Access Token will stop working when an existing user gains access to a second customer.

See End-user authentication for the complete credential-verification flow, token exchange, and customer switching.

auth_token field naming

Some API descriptions and SDK methods use auth_token as the field name for any end-user session token. Pass the Access Token once the user is acting for an customer. The field name remains for backward compatibility.

SDK capability matrix

Some authentication factors and secure components are mobile-only. Use the following matrix when planning your auth and instrumentInstrumentA financial product owned by a customer. 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 ProvisioningA 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). 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). 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). 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). Know Your Customer - the identity verification process for consumer customers. This process allows you to securely verify your user's identity. Weavr asks users to submit the information and documentation they need for approval by financial providers. / KYBKYB (Know Your Business). Know Your Business - the identity verification process for corporate customers. This process allows you to securely verify your business customer's identity. Weavr asks users to submit the information and documentation they need for approval 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.