Crear usuario autorizado

Agrega un usuario existente de Fluz a la cuenta del solicitante como usuario autorizado con uno o más roles de acceso. Esta mutación no crea un usuario: busca un usuario existente de Fluz por email o teléfono y luego crea una asignación de rol en la cuenta del solicitante (o reactiva una asignación previamente DECLINED/INACTIVE con los nuevos roles). La cuenta de destino siempre se resuelve a partir de las credenciales del solicitante: los tokens Bearer usan la cuenta del token; las llamadas Basic (clave de API) usan la cuenta operadora configurada de la aplicación. No hay forma de dirigir una cuenta que no posees a través de este endpoint. 🔒 Acceso restringido Esta mutación requiere el alcance MANAGE_SUBUSERS. Admite autenticación Bearer (token de acceso de usuario) y Basic (<API_KEY>). El rol OWNER no puede asignarse a través de este 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
    }
  }
}

Parámetros

Parámetro	Tipo	Requerido	Descripción
email	String	No*	Dirección de email del usuario de Fluz existente que se va a autorizar. *Se requiere al menos uno de `email` o `phone`.
phone	String	No*	Número de teléfono del usuario de Fluz existente que se va a autorizar. *Se requiere al menos uno de `email` o `phone`.
roles	[UACRoleType!]!	Sí	Uno o más roles a asignar. Valores permitidos: `ADMIN`, `MANAGER`, `SPENDER`, `VIEWER`. `OWNER` no está permitido.
status	UACRoleStatusType	No	El estado inicial para la asignación de rol. Predetermina a `PENDING`. Establécelo en `ACTIVE` para omitir el estado pendiente y activar la asignación de inmediato (no se requiere aceptación). Valores permitidos: `PENDING`, `ACTIVE`, `INACTIVE`, `DECLINED`.
sendInvite	Boolean	No	Si se debe enviar la invitación de asignación de rol al usuario. Predetermina a `true`. Establécelo en `false` para crear la asignación sin enviar una invitación, haciendo que la invitación sea opcional.

Respuesta

Respuesta exitosa

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

Campos de la respuesta

Campo	Tipo	Descripción
`success`	Boolean	`true` si la asignación de rol se creó o reactivó correctamente.
`authUserId`	UUID	El ID del usuario autorizado (ID de la asignación de rol UAC). Usa este valor al llamar a `removeAuthorizedUser` o al filtrar resultados de `authorizedUsers`.
`roles`	[UACRoleType]	Los roles asignados al usuario en esta cuenta.
`status`	UACRoleStatusType	Estado de la asignación de rol: `PENDING`, `ACTIVE`, `INACTIVE` o `DECLINED`.
`pendingActionId`	UUID	El ID de acción pendiente para la invitación, si se creó una (se devuelve cuando la asignación requiere aceptación del usuario).
`error`	AuthorizedUserError	Si `success` es false, un objeto de Error que contiene `code` y `message`.

Nota: Esta mutación devuelve errores en los datos de la respuesta, no como errores de GraphQL. Verifica siempre el campo success y maneja el objeto error cuando success sea false.

Ejemplo de solicitud

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);
}

Omitir el estado pendiente y suprimir la invitación

Para activar al usuario autorizado de inmediato sin enviar una invitación, establece status en ACTIVE y sendInvite en false. La asignación se crea en estado ACTIVE, no se devuelve pendingActionId y no se envía invitación al usuario.

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
  }
}'

Códigos de error

Código	Mensaje	Descripción
`ARG-0002`	Missing required arguments	No se proporcionó `email` ni `phone`, o `roles` está vacío. Se necesita al menos un identificador y al menos un rol.
`ARG-0001`	Invalid arguments received	Uno o más valores en `roles` no están permitidos (por ejemplo, `OWNER`), o `status` no es uno de `PENDING`, `ACTIVE`, `INACTIVE`, `DECLINED`. Usa `ADMIN`, `MANAGER`, `SPENDER` o `VIEWER` para roles.
`AUTH-0008`	Invalid user access	No se pudo resolver el solicitante a partir del token de acceso o la clave de API, o la aplicación con autenticación Basic no tiene una cuenta operadora configurada. Verifica tus credenciales de autenticación.
`AUTH-0031`	The requested scopes must be granted by the user first.	Al token le falta el alcance `MANAGE_SUBUSERS` requerido para gestionar usuarios autorizados.
`AUTH-0034`	No Fluz user found with the provided email or phone number.	Ningún usuario existente de Fluz coincide con el `email` o `phone` proporcionado. El usuario de destino ya debe tener una cuenta de Fluz.
`AUTH-0035`	This user already has an active role assignment on this account.	El usuario ya está autorizado en la cuenta del solicitante. Usa `removeAuthorizedUser` primero si necesitas reasignar roles.
`AUTH-0037`	Unable to manage authorized user. Please try again or contact support.	Ocurrió una falla general al crear la asignación de rol. Vuelve a intentarlo o contacta al soporte.

​Parámetros

​Respuesta

​Respuesta exitosa

​Campos de la respuesta

​Ejemplo de solicitud

​Omitir el estado pendiente y suprimir la invitación

​Códigos de error