Create Auth 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!]!
) {
  addAuthorizedUser(
    email: $email
    phone: $phone
    roles: $roles
  ) {
    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.

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": "[email protected]",
    "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: "[email protected]",
      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);
}

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`). Use `ADMIN`, `MANAGER`, `SPENDER`, or `VIEWER`.
`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.