> ## 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. # 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 (``) authentication. The `OWNER` role cannot be assigned through this endpoint. ```graphql theme={null} 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 ```json theme={null} { "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 theme={null} curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -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"] } }' ``` ```typescript theme={null} 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 theme={null} curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -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. |