建立授權使用者

將現有的 Fluz 使用者以一個或多個存取角色新增為呼叫者帳戶的授權使用者。此 mutation 不會建立新使用者——它會透過電子郵件或電話號碼查找現有的 Fluz 使用者，然後在呼叫者的帳戶上建立角色指派（或以新角色重新啟用先前為 DECLINED/INACTIVE 的指派）。目標帳戶一律從呼叫者的憑證解析而來——使用 Bearer 權杖時採用該權杖的帳戶；使用 Basic（API 金鑰）呼叫時則使用應用程式所設定的營運者帳戶。無法透過此端點將動作指向非自身擁有的帳戶。 🔒 限制存取此 mutation 需要 MANAGE_SUBUSERS 權限範圍。支援 Bearer（使用者存取權杖）與 Basic（<API_KEY>）驗證。無法透過此端點指派 OWNER 角色。

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

參數

參數	型別	必填	說明
email	String	否*	要授權的現有 Fluz 使用者之電子郵件地址。*`email` 或 `phone` 至少擇一必填。
phone	String	否*	要授權的現有 Fluz 使用者之電話號碼。*`email` 或 `phone` 至少擇一必填。
roles	[UACRoleType!]!	是	要指派的一個或多個角色。允許的值：`ADMIN`、`MANAGER`、`SPENDER`、`VIEWER`。不允許 `OWNER`。
status	UACRoleStatusType	否	角色指派的初始狀態。預設為 `PENDING`。設定為 `ACTIVE` 可略過待處理狀態並立即啟用指派（不需接受）。允許的值：`PENDING`、`ACTIVE`、`INACTIVE`、`DECLINED`。
sendInvite	Boolean	否	是否傳送角色指派邀請給使用者。預設為 `true`。設為 `false` 會在不傳送邀請的情況下建立指派，使邀請成為可選項。

回應

成功回應

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

回應欄位

欄位	型別	說明
`success`	Boolean	若成功建立或重新啟用角色指派則為 `true`。
`authUserId`	UUID	授權使用者 ID（UAC 角色指派 ID）。呼叫 `removeAuthorizedUser` 或在 `authorizedUsers` 篩選結果時請使用此值。
`roles`	[UACRoleType]	在此帳戶上指派給該使用者的角色。
`status`	UACRoleStatusType	角色指派的狀態：`PENDING`、`ACTIVE`、`INACTIVE` 或 `DECLINED`。
`pendingActionId`	UUID	邀請的待處理動作 ID（若已建立，且當指派需要使用者接受時會回傳）。
`error`	AuthorizedUserError	若 `success` 為 false，則為包含 `code` 與 `message` 的錯誤物件。

注意：此 mutation 會在回應資料中回傳錯誤，而非作為 GraphQL errors。請一律檢查 success 欄位，並在 success 為 false 時處理 error 物件。

範例請求

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

略過待處理狀態並抑制邀請

若要在不傳送邀請的情況下立即啟用授權使用者，請將 status 設為 ACTIVE 並將 sendInvite 設為 false。指派會以 ACTIVE 狀態建立，不會回傳 pendingActionId，也不會傳送邀請給使用者。

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

錯誤代碼

代碼	訊息	說明
`ARG-0002`	缺少必要參數	未提供 `email` 或 `phone`，或 `roles` 為空。需要至少一個識別資訊與至少一個角色。
`ARG-0001`	收到無效參數	`roles` 中一或多個值不被允許（例如 `OWNER`），或 `status` 不是 `PENDING`、`ACTIVE`、`INACTIVE`、`DECLINED` 其中之一。角色請使用 `ADMIN`、`MANAGER`、`SPENDER` 或 `VIEWER`。
`AUTH-0008`	無效的使用者存取	無法從存取權杖或 API 金鑰解析呼叫者，或使用 Basic 驗證的應用程式未設定營運者帳戶。請驗證您的驗證憑證。
`AUTH-0031`	使用者必須先授與所要求的 scopes。	權杖缺少管理授權使用者所需的 `MANAGE_SUBUSERS` 權限範圍。
`AUTH-0034`	找不到具有提供之電子郵件或電話號碼的 Fluz 使用者。	沒有現有的 Fluz 使用者符合所提供的 `email` 或 `phone`。目標使用者必須已擁有 Fluz 帳戶。
`AUTH-0035`	此使用者已在此帳戶上擁有使用中的角色指派。	該使用者已被授權於呼叫者的帳戶。若需重新指派角色，請先使用 `removeAuthorizedUser`。
`AUTH-0037`	無法管理授權使用者。請再試一次或聯絡支援。	在建立角色指派時發生一般性錯誤。請重試或聯絡支援。

​參數

​回應

​成功回應

​回應欄位

​範例請求

​略過待處理狀態並抑制邀請

​錯誤代碼

參數

回應

成功回應

回應欄位

範例請求

略過待處理狀態並抑制邀請

錯誤代碼