> ## 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.

# 建立授權使用者

將現有的 Fluz 使用者以一個或多個存取角色新增為呼叫者帳戶的授權使用者。此 mutation 不會建立新使用者——它會透過電子郵件或電話號碼查找現有的 Fluz 使用者，然後在呼叫者的帳戶上建立角色指派（或以新角色重新啟用先前為 `DECLINED`/`INACTIVE` 的指派）。

目標帳戶一律從呼叫者的憑證解析而來——使用 Bearer 權杖時採用該權杖的帳戶；使用 Basic（API 金鑰）呼叫時則使用應用程式所設定的營運者帳戶。無法透過此端點將動作指向非自身擁有的帳戶。

🔒 限制存取

此 mutation 需要 `MANAGE_SUBUSERS` 權限範圍。支援 Bearer（使用者存取權杖）與 Basic（`<API_KEY>`）驗證。無法透過此端點指派 `OWNER` 角色。

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

<br />

### 參數

| 參數         | 型別                | 必填  | 說明                                                                                                        |
| :--------- | :---------------- | :-- | :-------------------------------------------------------------------------------------------------------- |
| 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` 會在不傳送邀請的情況下建立指派，使邀請成為可選項。                                            |

<br />

### 回應

#### 成功回應

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

<br />

### 回應欄位

| 欄位                | 型別                  | 說明                                                                               |
| :---------------- | :------------------ | :------------------------------------------------------------------------------- |
| `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` 的錯誤物件。                               |

<br />

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

### 範例請求

```curl theme={null}
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"]
  }
}'
```

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

<br />

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

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

```curl theme={null}
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` | 無法管理授權使用者。請再試一次或聯絡支援。        | 在建立角色指派時發生一般性錯誤。請重試或聯絡支援。                                                                                                                |

<br />