Create Authorized User

Add an existing Fluz user to the caller’s account as an authorized user with one or more access roles. This mutation does not create a user — it looks up an existing Fluz user by email or phone, then creates a role assignment on the caller’s account (or reactivates a previously DECLINED/INACTIVE assignment with the new roles). The target account is always resolved from the caller’s credentials — Bearer tokens use the token’s account; Basic (API key) callers use the application’s configured operator account. There is no way to target an account you do not own through this endpoint. 🔒 Restricted Access This mutation requires the MANAGE_SUBUSERS scope. It supports both Bearer (user access token) and Basic (<API_KEY>) authentication. The OWNER role cannot be assigned through this endpoint.

mutation AddAuthorizedUser(
  $email: String
  $phone: String
  $roles: [UACRoleType!]!
  $status: UACRoleStatusType
  $sendInvite: Boolean
) {
  addAuthorizedUser(
    email: $email
    phone: $phone
    roles: $roles
    status: $status
    sendInvite: $sendInvite
  ) {
    success
    authUserId
    roles
    status
    pendingActionId
    error {
      code
      message
    }
  }
}

Parameters

Parameter	Type	Required	Description
email	String	No*	Email address of the existing Fluz user to authorize. *At least one of `email` or `phone` is required.
phone	String	No*	Phone number of the existing Fluz user to authorize. *At least one of `email` or `phone` is required.
roles	[UACRoleType!]!	Yes	One or more roles to assign. Allowed values: `ADMIN`, `MANAGER`, `SPENDER`, `VIEWER`. `OWNER` is not allowed.
status	UACRoleStatusType	No	The initial status for the role assignment. Defaults to `PENDING`. Set to `ACTIVE` to skip the pending state and activate the assignment immediately (no acceptance required). Allowed values: `PENDING`, `ACTIVE`, `INACTIVE`, `DECLINED`.
sendInvite	Boolean	No	Whether to send the role assignment invite to the user. Defaults to `true`. Set to `false` to create the assignment without sending an invite, making the invitation optional.

Response

Success Response

{
  "data": {
    "addAuthorizedUser": {
      "success": true,
      "authUserId": "8b2c1e0a-7d4f-4a9b-9c2d-1f3e4a5b6c7d",
      "roles": ["MANAGER", "VIEWER"],
      "status": "PENDING",
      "pendingActionId": "2f7c1a3b-9e44-4d2a-8a91-c1b2d3e4f5a6",
      "error": null
    }
  }
}

Response Fields

Field	Type	Description
`success`	Boolean	`true` if the role assignment was successfully created or reactivated.
`authUserId`	UUID	The authorized user ID (UAC role assignment ID). Use this value when calling `removeAuthorizedUser` or filtering results from `authorizedUsers`.
`roles`	[UACRoleType]	The roles assigned to the user on this account.
`status`	UACRoleStatusType	Status of the role assignment: `PENDING`, `ACTIVE`, `INACTIVE`, or `DECLINED`.
`pendingActionId`	UUID	The pending action ID for the invite, if one was created (returned when the assignment requires user acceptance).
`error`	AuthorizedUserError	If `success` is false, an Error object containing `code` and `message`.

Note: This mutation returns errors in the response data, not as GraphQL errors. Always check the success field and handle the error object when success is false.

Example Request

curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
  "query": "mutation AddAuthorizedUser($email: String, $phone: String, $roles: [UACRoleType!]!) { addAuthorizedUser(email: $email, phone: $phone, roles: $roles) { success authUserId roles status pendingActionId error { code message } } }",
  "variables": {
    "email": "teammate@example.com",
    "roles": ["MANAGER", "VIEWER"]
  }
}'

const response = await fetch('https://transactional-graph.staging.fluzapp.com/api/v1/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`
  },
  body: JSON.stringify({
    query: `
      mutation AddAuthorizedUser(
        $email: String
        $phone: String
        $roles: [UACRoleType!]!
      ) {
        addAuthorizedUser(
          email: $email
          phone: $phone
          roles: $roles
        ) {
          success
          authUserId
          roles
          status
          pendingActionId
          error {
            code
            message
          }
        }
      }
    `,
    variables: {
      email: "teammate@example.com",
      roles: ["MANAGER", "VIEWER"]
    }
  })
});

const data = await response.json();

if (data.data.addAuthorizedUser.success) {
  console.log('Authorized user added:', data.data.addAuthorizedUser);
} else {
  console.error('Add authorized user failed:', data.data.addAuthorizedUser.error);
}

Skip the pending state and suppress the invite

To activate the authorized user immediately without sending an invite, set status to ACTIVE and sendInvite to false. The assignment is created in the ACTIVE state, no pendingActionId is returned, and no invite is sent to the user.

curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
  "query": "mutation AddAuthorizedUser($email: String, $phone: String, $roles: [UACRoleType!]!, $status: UACRoleStatusType, $sendInvite: Boolean) { addAuthorizedUser(email: $email, phone: $phone, roles: $roles, status: $status, sendInvite: $sendInvite) { success authUserId roles status pendingActionId error { code message } } }",
  "variables": {
    "email": "teammate@example.com",
    "roles": ["MANAGER", "VIEWER"],
    "status": "ACTIVE",
    "sendInvite": false
  }
}'

Error Codes

Code	Message	Description
`ARG-0002`	Missing required arguments	Neither `email` nor `phone` was provided, or `roles` is empty. At least one identifier and at least one role are needed.
`ARG-0001`	Invalid arguments received	One or more values in `roles` are not allowed (for example, `OWNER`), or `status` is not one of `PENDING`, `ACTIVE`, `INACTIVE`, `DECLINED`. Use `ADMIN`, `MANAGER`, `SPENDER`, or `VIEWER` for roles.
`AUTH-0008`	Invalid user access	The caller could not be resolved from the access token or API key, or the Basic-auth application has no operator account configured. Verify your authentication credentials.
`AUTH-0031`	The requested scopes must be granted by the user first.	The token is missing the `MANAGE_SUBUSERS` scope required to manage authorized users.
`AUTH-0034`	No Fluz user found with the provided email or phone number.	No existing Fluz user matches the supplied `email` or `phone`. The target user must already have a Fluz account.
`AUTH-0035`	This user already has an active role assignment on this account.	The user is already authorized on the caller’s account. Use `removeAuthorizedUser` first if you need to reassign roles.
`AUTH-0037`	Unable to manage authorized user. Please try again or contact support.	A general failure occurred while creating the role assignment. Please retry or contact support.

​Parameters

​Response

​Success Response

​Response Fields

​Example Request

​Skip the pending state and suppress the invite

​Error Codes