> ## 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.

# Authorized users

> Add users to an organization beyond the primary controller — invited via email, with permissions you assign, and without going through the bank account application KYC flow.

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

| Aspect               | Primary controller                                                              | Authorized user                                                                                                                   |
| :------------------- | :------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------- |
| How they exist       | Created implicitly when the bank account application is submitted and approved. | Created explicitly via `POST /identity/v1/users`.                                                                                 |
| KYC/KYB              | Full 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 source      | The applicant identity captured on the application.                             | Whatever email you supply on create. Tesouro emails the user if `status: INVITED`.                                                |
| Required at boarding | Yes — 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.

```bash title="Create an invited user" lines theme={null}
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"]
  }'
```

| Field            | Description                                                                                                                         |
| :--------------- | :---------------------------------------------------------------------------------------------------------------------------------- |
| `email`          | The user's email. Used as the lookup key and, when `status: INVITED`, as the destination for the invitation email.                  |
| `name`           | The user's display name.                                                                                                            |
| `role`           | The platform role to grant (e.g. `MEMBER`, `ADMIN`). Roles are organization-level; the bank's program defines what each can do.     |
| `status`         | `INVITED` to send an invitation email and create the user in a pending state, or `ACTIVE` to provision them immediately.            |
| `permissionKeys` | An 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](/embedded-banking/guides/users/api-access) or [wrap it in a widget JWE](/embedded-banking/guides/users/widget-tokens) — 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.