Authorized User Overview

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, 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 (`<API_KEY>`)	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.

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	`addAuthorizedUser`	`MANAGE_SUBUSERS`	Grant an existing Fluz user one or more roles on your account.
Query authorized users	`authorizedUsers`	`VIEW_SUBUSERS`	List everyone with a role assignment on your account, optionally filtered.
Remove an authorized user	`removeAuthorizedUser`	`MANAGE_SUBUSERS`	Revoke access by deactivating the role assignment.
Create a virtual card for an 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.

Add them as an authorized user

Call addAuthorizedUser and hold on to the returned authUserId. Continue only once the status is ACTIVE.

Save a billing address

Call addVirtualCardAddress with the authUserId to store a billing address for that cardholder.

Create the card

Call createVirtualCard with input.authUserId and the returned userAddressId.

See 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:

{
  "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.

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.

Want to learn more? Speak with our experts for more info or to request a demo.

​How Access Is Scoped

​Roles

​Status Lifecycle

​What You Can Do

​Issuing Cards for Authorized Users

​Error Handling

​Requirements

How Access Is Scoped

Roles

Status Lifecycle

What You Can Do

Issuing Cards for Authorized Users

Error Handling

Requirements