> ## Documentation Index > Fetch the complete documentation index at: https://docs.fluz.app/llms.txt > Use this file to discover all available pages before exploring further. # Authorized User Overview > Give other Fluz users scoped access to your account, control what they can do with roles, and issue virtual cards on their behalf. An **authorized user** is an existing Fluz user who has been granted one or more roles on your account. Authorized users let a business put a team on one account — a bookkeeper who can only view activity, a manager who can approve spend, a contractor who can spend from a single card — without sharing a login or handing over the full account balance. Authorized user management is a small, self-contained part of the API: one mutation to add, one query to list, one mutation to remove, and an `authUserId` you can pass into virtual card operations to issue cards on someone else's behalf. **Adding an authorized user does not create a Fluz user.** `addAuthorizedUser` looks up an **existing** Fluz user by email or phone and creates a role assignment for them on your account. If the person does not have a Fluz account yet, register them first with [User Registration](/features/user-registration), then add them. *** ## How Access Is Scoped The target account is always resolved from the caller's credentials — there is no account ID parameter, and no way to manage authorized users on an account you do not control: | Authentication | Account acted on | | -------------------------- | ---------------------------------------------- | | Bearer (user access token) | The account the token was issued for. | | Basic (``) | The application's configured operator account. | Every authorized user is identified by an **`authUserId`** — the ID of the role assignment, not the user. You get it back from `addAuthorizedUser` and from `authorizedUsers`, and you pass it to `removeAuthorizedUser`, `addVirtualCardAddress`, and `createVirtualCard`. *** ## Roles Roles are assigned with the `UACRoleType` enum. An authorized user can hold more than one role, and the effective access is the highest of them. | Role | Assignable | Typical use | | --------- | ---------- | ----------------------------------------------------------------------------- | | `OWNER` | No | The account holder. Cannot be assigned or removed through the API. | | `ADMIN` | Yes | Full management of the account, its funds, cards, and other authorized users. | | `MANAGER` | Yes | Oversight of spend — reviewing and approving requests from other users. | | `SPENDER` | Yes | Day-to-day spending on the cards and spend accounts they have access to. | | `VIEWER` | Yes | Read-only visibility into account activity. | Roles are set at the time you add the user. To change someone's roles, remove the assignment and add it again with the new role set. *** ## Status Lifecycle Every role assignment carries a `UACRoleStatusType` status: | Status | Meaning | | ---------- | ---------------------------------------------------------------------------------- | | `PENDING` | The invite has been created and is waiting for the user to accept. | | `ACTIVE` | The user has access to the account with the assigned roles. | | `DECLINED` | The user rejected the invite. | | `INACTIVE` | Access has been revoked, either by removal or by the assignment being deactivated. | ```mermaid theme={null} stateDiagram-v2 [*] --> PENDING PENDING --> ACTIVE PENDING --> DECLINED ACTIVE --> INACTIVE INACTIVE --> ACTIVE DECLINED --> ACTIVE ``` By default, `addAuthorizedUser` creates the assignment as `PENDING` and sends an invite. If your product already handles its own consent flow, you can set `status: ACTIVE` and `sendInvite: false` to provision the user immediately with no invite and no acceptance step. Re-adding a user whose assignment is `INACTIVE` or `DECLINED` reactivates that assignment with the new roles rather than creating a duplicate. **`PENDING` assignments cannot be used yet.** An `authUserId` must be `ACTIVE` before you can save a billing address or create a virtual card for that user. If `addAuthorizedUser` returns `PENDING`, wait for acceptance before calling `addVirtualCardAddress` or `createVirtualCard`. *** ## What You Can Do | Action | Query / Mutation | Scope | Description | | ------------------------------------------------------------------------------------------------- | ---------------------- | -------------------- | -------------------------------------------------------------------------- | | [Create an authorized user](/features/create-authorized-users) | `addAuthorizedUser` | `MANAGE_SUBUSERS` | Grant an existing Fluz user one or more roles on your account. | | [Query authorized users](/features/query-authorized-user) | `authorizedUsers` | `VIEW_SUBUSERS` | List everyone with a role assignment on your account, optionally filtered. | | [Remove an authorized user](/features/remove-authorized-user) | `removeAuthorizedUser` | `MANAGE_SUBUSERS` | Revoke access by deactivating the role assignment. | | [Create a virtual card for an authorized user](/features/create-virtual-card-for-authorized-user) | `createVirtualCard` | `CREATE_VIRTUALCARD` | Issue a card in the authorized user's name that stays on your account. | `addAuthorizedUser`, `authorizedUsers`, and `removeAuthorizedUser` accept both Bearer and Basic authentication. `createVirtualCard` requires a Bearer token. *** ## Issuing Cards for Authorized Users A virtual card created with `input.authUserId` is issued against the authorized user's cardholder record — the card carries their name and returns their `userId` — while the card itself, its funding, and its transactions remain on your account. This is how you put a card in an employee's or contractor's hands without opening a separate account for them. The full sequence is: Skip this if they already have a Fluz account. Otherwise call `registerUser`. Call `addAuthorizedUser` and hold on to the returned `authUserId`. Continue only once the status is `ACTIVE`. Call `addVirtualCardAddress` with the `authUserId` to store a billing address for that cardholder. Call `createVirtualCard` with `input.authUserId` and the returned `userAddressId`. See [Create Virtual Card for Authorized User](/features/create-virtual-card-for-authorized-user) for the complete request and response reference. *** ## Error Handling The authorized user operations return errors **in the response data**, not as GraphQL errors. Always check `success` and read the `error` object when it is `false`: ```json theme={null} { "data": { "addAuthorizedUser": { "success": false, "authUserId": null, "error": { "code": "AUTH-0034", "message": "No Fluz user found with the provided email or phone number." } } } } ``` The codes you are most likely to hit: | Code | When it happens | | ----------- | ------------------------------------------------------------------------------------ | | `AUTH-0031` | The token is missing `MANAGE_SUBUSERS` or `VIEW_SUBUSERS`. | | `AUTH-0034` | No Fluz user matches the email or phone, or the `authUserId` is not on your account. | | `AUTH-0035` | The user already has an active role assignment on your account. | | `AUTH-0036` | You tried to remove the account owner. | | `AUTH-0037` | A general failure occurred managing the role assignment. Retry or contact support. | `createVirtualCard` behaves differently — it raises standard GraphQL errors, including `VC-0020` when a billing address is still pending issuer approval. See [Virtual Card Error Codes](/features/virtual-card-error-codes). *** ## Requirements Listing authorized users requires the `VIEW_SUBUSERS` scope. Adding and removing them requires `MANAGE_SUBUSERS`. Issuing a card on their behalf requires `CREATE_VIRTUALCARD`. Confirm your user access token carries the right scopes before calling these operations — see [Application Scopes](/features/application-scopes). *** **Want to learn more?** Speak with our experts for more info or to request a demo.