Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tesouro.com/llms.txt

Use this file to discover all available pages before exploring further.

The primary controller on a bank account application is the only user who needs to pass the application’s KYC/KYB checks. Once the application reaches COMPLETE and the organization is live, you can add more users — accountants, ops staff, additional owners, anyone who needs to log in — without putting any of them through the application flow. These are authorized users.

​
When you need them

  • The signed-up business has more than one person who needs access. The controller did onboarding; a bookkeeper now needs read access to balances and transfers.
  • A platform admin at your company (Northfield Software) needs to log into a customer’s organization for support — invite an admin user rather than impersonating the controller.
  • You are migrating users from an existing system and want each one to land as their own identity rather than collapsing them all onto a shared login.
If you only ever need one human per customer organization — the controller alone — you can skip this page entirely. The application flow already provisioned that user.

​
How it differs from the controller

AspectPrimary controllerAuthorized user
How they existCreated implicitly when the bank account application is submitted and approved.Created explicitly via POST /identity/v1/users.
KYC/KYBFull applicant KYC plus business KYB on the application.No application-level KYC. The bank’s program rules govern what they can do; identity is verified by the controller inviting them.
Identity sourceThe applicant identity captured on the application.Whatever email you supply on create. Tesouro emails the user if status: INVITED.
Required at boardingYes — there is no application without one.No — added after the organization is live.
The controller is a beneficial-owner-grade record on the application; an authorized user is a permission-grade record on the organization. Don’t try to add additional beneficial owners through this endpoint — those belong on the application’s businessOwners array.

​
Creating an authorized user

POST /identity/v1/users creates the user inside an organization. The endpoint accepts both APP and USER tokens; your backend can mint users using its client-credentials token, or a user with the user:write:all scope can mint additional users from the organization itself.
Create an invited user
curl -X POST 'https://api.sandbox.tesouro.com/identity/v1/users' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "bookkeeper@northfield-customer.example",
    "name":  "Alex Morgan",
    "role":  "MEMBER",
    "status": "INVITED",
    "permissionKeys": ["user:read", "bank-account:read"]
  }'
FieldDescription
emailThe user’s email. Used as the lookup key and, when status: INVITED, as the destination for the invitation email.
nameThe user’s display name.
roleThe platform role to grant (e.g. MEMBER, ADMIN). Roles are organization-level; the bank’s program defines what each can do.
statusINVITED to send an invitation email and create the user in a pending state, or ACTIVE to provision them immediately.
permissionKeysAn array of permission keys to grant. Prefer this over permissionIds for new integrations. The two fields are mutually exclusive.
To create the user inside a child organization (a platform caller acting on behalf of a customer’s org), set X-Organization-ID to that child org’s ID. Without the header, the user lands in the caller’s own organization.

​
Invitation vs immediate activation

  • INVITED — Tesouro emails the user a one-time invitation link. They follow the link, complete sign-in on their OIDC provider, and the platform marks them ACTIVE. Use this when the user owns the email account and will set up their own access.
  • ACTIVE — The user is created already-active and skips the invitation step. Use this when your platform is doing single sign-on and the user will arrive with a valid JWT — there is no separate sign-up step to run.
A user that stays INVITED for too long can be re-sent the invitation; an ACTIVE user that needs to be paused can be disabled rather than deleted.

​
Calling Tesouro as an authorized user

Once a user is ACTIVE, your backend can mint a JWT for them and either exchange it for a REST access token or wrap it in a widget JWE — the same two flows you use for the controller. Tesouro does not distinguish controller from authorized user at the token layer; what differs is the role and permission set you assigned at create time.