Authorized User Use Cases
An Authorized User is a person record attached to a Customer. Unit uses this record when an individual's identity must be recognized — for authentication, verification, or incoming payment name matching — separate from your own application's user permissions.
This page explains when to add authorized users, when you do not need them, and how they relate to common partner integration patterns.
Application permissions vs Authorized Users
Most partners maintain their own role-based access control (who can initiate payments, edit counterparties, approve wires, and so on). That is expected and remains your responsibility.
An authorized user at Unit is not a substitute for permissions in your product, and your product permissions are not a substitute for an authorized user when Unit or the bank must validate an individual's authority.
| Layer | What it controls | Who manages it |
|---|---|---|
| Your product | Which end users can perform which actions in your product | You |
| Partner org token | Server-side API calls your backend makes on behalf of customers | You (via your org bearer token) |
| Customer token | Front-end or component access scoped to one customer | You create tokens; Unit enforces scopes |
| Authorized user record | Which real people Unit recognizes on a customer for identity-linked flows (two-factor authentication (2FA) routing, verification callbacks, incoming name matching, exchange-network access) | You add via Add Authorized Users |
Adding someone as an authorized user registers a person at the customer level. It does not, by itself, grant or restrict specific actions inside your application. Conversely, giving someone payment permissions in your app does not automatically register them with Unit unless you also add them as an authorized user where an identity-linked flow requires it.
When you need an Authorized User
Add an authorized user when Unit must be able to identify a specific person on the customer account. Common cases:
| Use case | Why an authorized user is needed |
|---|---|
| Two-factor authentication (2FA) for a non-primary contact | Route one-time password (OTP) to an authorized user's phone when creating a customer token or using user interface (UI) components |
| Programmatic authentication (JSON Web Token, JWT) | Business customers can map a JWT sub claim to a contact or authorized user's jwtSubject when creating customer tokens |
| Transaction verification callbacks | For higher-risk outbound payments (for example, wires above your bank partner's callback threshold), the person completing phone verification should be established as an authorized user in advance |
| Incoming payment name matching | Payments payable to an individual associated with a business account are matched against known names on the customer, including authorized users |
| Plaid Exchange / financial data aggregation | Authorized users can connect through exchange networks; use canConnectWithAuthVendor to control this per person |
| Check deposit send links | Optionally send verification codes via short message service (SMS) to an existing authorized user's phone (see caution below) |
Do not add an authorized user only at the moment a high-risk transaction requires verification. Individuals who may routinely complete verification should be added and validated before they are needed.
When you do not need an Authorized User
You generally do not need to add authorized users for every person who can initiate activity through your product.
| Pattern | Authorized user required? |
|---|---|
| Server-side payment origination using your org bearer token (ACH, wires, book payments, and so on) | No — the API call is made by your backend; Unit does not require an authorized user record for the end user who clicked "Pay" in your UI |
| Counterparty create/update via your org token | No — manage editor permissions in your product |
| Card or account management performed entirely server-side with your org token | No |
| Narrow product roles (for example, "counterparty editor only") with no identity-linked Unit flow | No — unless that person also needs one of the identity cases above |
Maintain internal records and controls for who may initiate and approve transactions in your product. Authorized users complement those controls for situations where Unit or the bank must validate a person's identity.
Common integration patterns
Originating payments with your org token
If your integration originates payments from your backend using your organization bearer token, you do not need to register each payment initiator as an authorized user solely because they can create a payment in your application.
Your org token authorizes the API request. Implement approval workflows, limits, and entitlements in your product as you see fit.
For higher-risk payments, your bank partner may require additional verification. When a callback is needed, the person who completes verification should already be on the customer's authorized user list with a phone number that matches what they use on the call.
See Outgoing Wire Payment Workflow for wire review and callback requirements.
Customer tokens and UI components
When end users interact with Unit through customer tokens or UI components, authorized users matter for who receives 2FA and who can authenticate.
For business customers, OTP is sent to the business contact's phone by default. To send OTP to a different person, add them as an authorized user and reference them when creating the customer token:
- Pass
authorizedUserResourceon Create Customer Token (used by components withupgradableScope) - Or pass the authorized user's
phoneon Create Customer Token Verification
In these flows, authorized users can authenticate and act within the scopes you grant on the customer token — this is what Overview describes as access to the customer's financials.
Plaid Exchange and financial data aggregation
Authorized users can connect customer accounts through exchange networks such as Plaid Exchange. By default, canConnectWithAuthVendor is true when an authorized user is created.
Set canConnectWithAuthVendor to false for individuals who should not link accounts through Plaid. To change this field later, add the authorized user again with the same email and the updated value (existing records are updated per the Add Authorized Users API). See Authorized User Resources for the field definition.
Authorized users are associated with the customer, not a single deposit account. Exchange-network access may expose multiple accounts under that customer unless you restrict connectivity. See Customer token resources for token-level account scoping in customer-token flows.
Two-factor authentication (2FA) and OTP
Authorized users are commonly used when a business has multiple people who need to complete 2FA, not only the primary business contact.
Typical flows:
- UI components — pass
authorizedUserResourcewhen creating the customer token so the component sends SMS to the authorized user. See Authentication. - Customer token verification API — provide an authorized user's phone on the verification request so OTP goes to that person instead of the primary contact.
Programmatic authentication (JWT)
For customer tokens created with a JWT, business customers must have a matching jwtSubject on the contact or on at least one authorized user. This lets your identity provider (IdP) identify which end user is authenticating without a separate OTP step when JWT is used.
Incoming payment name matching
When an incoming ACH, wire, or check is payable to a name associated with a business customer, Unit matches the payee name against known names on the customer — including authorized users, beneficial owners, officer, doing business as (DBA) name, and aliases.
Add an authorized user when a real person regularly receives funds under their own name on a business account and you want their name recognized during automated matching.
Authorized users must be real people authorized on the account. Do not use authorized users to store alternate business names — update the business customer's DBA or request an alias through Unit instead.
Transaction verification callbacks
Some bank partners require callback verification before releasing high-value or high-risk outbound payments (commonly wires above a configured threshold).
When a callback is required, your organization places a call to an authorized representative of the customer (see Outgoing Wire Payment Workflow). The person you reach must be the business contact, beneficial owner, officer, or an authorized user on that customer account, with a phone number that matches what is on file.
Best practice: Identify which individuals on the customer account may be contacted for callback verification, add them as authorized users during customer onboarding (or when their role is assigned), and keep the list current — do not add them only when a high-risk payment is already pending review.
Check deposit send links
For check deposit send links, verification SMS is sent to the customer's phone by default. You may pass an authorizedUser relationship to send the link to an existing authorized user and route the OTP to that person's phone on file.
The authorizedUser relationship references someone already on the customer's authorized user list — it does not create a new authorized user. For one-time depositors who are not authorized users, have the account holder complete verification on their own device rather than sharing OTP codes out of band.
Access control and limitations
No per-user permission roles at Unit
Unit does not offer granular authorized-user roles (for example, "counterparty editor only" or "wire approver only"). An enabled authorized user is a person record on the customer with:
Enabled/Disabledstatus (and evaluation status where applicable)- Optional
canConnectWithAuthVendorfor exchange-network access
Your application should enforce narrow permissions. Unit uses the authorized user list for identity-linked flows described on this page.
If you need role-based banking user experience (UX) with built-in permission tiers (Owner, Admin, ReadOnly, Cardholder), see Managed Banking multi-user access. That model is one end of the implementation spectrum; many partners combine org-token server-side flows with a smaller authorized-user roster for identity-linked cases only.
Disabling and removing authorized users
When someone no longer needs bank-recognizable identity on an account, remove them promptly. Do not rely on your product alone to revoke access that was granted at the Unit customer level.
Decision checklist
Use this checklist when onboarding a new role in your product:
- Does this person need to complete Unit 2FA (customer token or UI component) as themselves, not the primary contact? → Add as authorized user.
- Might this person complete bank callback verification on high-risk payments? → Add as authorized user before it is needed.
- Does this person's name appear on incoming payments to a business account? → Consider adding as authorized user.
- Should this person connect accounts via Plaid Exchange? → Add as authorized user; set
canConnectWithAuthVendorappropriately. - Do they only initiate payments or edit data through your backend org token, with no identity-linked Unit flow? → No authorized user required; enforce permissions in your product.
Related resources
| Resource | Description |
|---|---|
| Overview | Authorized user concepts |
| API | Add, get, list, and remove authorized users |
| Customer API Tokens | Customer tokens, 2FA, JWT, and resources |
| Authentication (UI components) | Component 2FA with authorizedUserResource |
| Outgoing Wire Payment Workflow | Wire review and callback requirements |