> ## Documentation Index
> Fetch the complete documentation index at: https://help.dingtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# アプリでの機密権限の使用

> 権限付与の体験と一般的な問題への対処方法を説明し、機密権限の管理をスムーズに完了できるよう支援します。

組織のコアデータに関わる機密性の高い API（連絡先の書き込み操作、マルチディメンションテーブルの読み書きなど）をアプリが呼び出す場合、厳格な権限付与フローを経る必要があります。本記事では、機密権限の概念、開発者の統合フロー、管理者による権限付与の体験、および一般的な問題への対処方法を体系的に紹介し、機密権限の管理をスムーズに完了できるよう支援します。

## 概念の紹介

### 機密権限とは

DingTalkオープンプラットフォームでは、企業のコアデータや高リスクな操作に関わる一部の権限が「機密権限」として定義されています。アプリは個別に申請し、組織管理者の明示的な権限付与を受けて初めて、関連する OpenAPI を呼び出すことができます。

現在公開されている主な機密権限は以下のとおりです。

<Note>
  指定されたロールを持つユーザーのみが、機密権限の付与または解除の操作を行うことができます。例えば、「全組織連絡先管理者」は `qyapi_manage_addresslist` 権限を付与できる唯一のロールです。
</Note>

| **権限スコープ code**            | **権限スコープの説明**                                                                                                  | **操作可能な権限スコープのロール**        |
| -------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------- |
| qyapi\_manage\_addresslist | 連絡先データ管理権限                                                                                                     | 全組織連絡先管理者                  |
| Notable.Base.Write         | DingTalkマルチディメンションテーブル書き込み権限  **重要**  マルチディメンションテーブルの権限スコープを拡張中のため、新規申請は現在受け付けておりません。特別なご要望はプロダクトチームまでご連絡ください。 | DingTalkドキュメント（ナレッジベース）管理者 |
| Notable.Base.Read          | DingTalkマルチディメンションテーブル読み取り権限  **重要**  マルチディメンションテーブルの権限スコープを拡張中のため、新規申請は現在受け付けておりません。特別なご要望はプロダクトチームまでご連絡ください。 | DingTalkドキュメント（ナレッジベース）管理者 |

### 全組織連絡先管理者とは

`qyapi_manage_addresslist` は、連絡先書き込み系 API を呼び出すための機密権限スコープであり、その権限付与操作は「全組織連絡先管理者」に限定されます。

このロールは、以下の 2 つの条件を同時に満たす必要があります。

* 連絡先のベーシック管理権限を持つこと
* 管理範囲が全組織であること

【全組織連絡先管理者】の確認パス：[OA管理画面](https://oa.dingtalk.io)にアクセスし、権限管理をクリックします。

### 統一権限付与スイートと authCode の説明

* **統一権限付与スイート**：DingTalkが提供する標準化された組織レベルの権限付与ソリューションであり、サードパーティアプリがクライアント組織に機密権限をリクエストするシナリオに適用されます。本スイートを統合することで、開発者は権限を付与する組織を権限付与フローに誘導し、一時的な認可コード（authCode）を取得できます。
* **authCode**：一時的な認可コードであり、ユーザーが権限付与を確認した後に DingTalkから返されます。有効期間は短く設定されています。開発者はこのコードを使用して API を呼び出し `access_token` と引き換え、保護された OpenAPI を呼び出す必要があります。

## 開発者の体験

### アプリ開発時の権限スコープの関連付け

> 本記事では、機密権限スコープ `qyapi_manage_addresslist` を例に説明します。

まず、開発者管理画面で機密権限スコープ `qyapi_manage_addresslist` をアプリに関連付ける必要があります。これにより、アプリは機密権限配下の OpenAPI を呼び出せるようになります —— ロールメンバーの管理範囲を設定します。

開発者管理画面に機密権限スコープ `qyapi_manage_addresslist` が表示されない場合は、テクニカルサポートに連絡し、業務上のニーズを説明してください。審査を通過後、プラットフォームが開発者組織に対して機密権限を公開します。

> 権限を申請した後、開発者はさらに DingTalk統一権限付与スイートを統合し、権限を付与する組織の管理者に通知して、権限付与組織の管理者に権限付与を行ってもらう必要があります。そうしないと、API 呼び出し時に 403 が表示されます。

### アプリによる OpenAPI の呼び出し

`access_token` を使用して対象の OpenAPI（部門の作成、ユーザーの更新など）を呼び出します。HTTP 200 が返れば呼び出しに成功したことを示します。ここでの開発者体験は、通常の権限スコープを使用する場合と同じです。

## 組織管理者の体験

### アプリの権限付与の有効化

* 通常の権限は、アプリの有効化時に管理者からアプリへ付与されます。
* 機密権限は、アプリの有効化に伴って有効になることはなく、該当するロールを持つ管理者がワークスペースに入って手動で権限付与を完了する必要があります。

### OA管理画面で監査ログを確認する

組織の OA管理画面では、機密権限に対する組織の操作（「アプリへの権限取得の承認」および「アプリに付与した権限の送信取消」など）を確認できます。

## よくある質問

### アプリが OpenAPI を呼び出した際に 403 が返された場合、どのように解決すればよいですか？

考えられる原因と解決策は以下のとおりです。

開発者管理画面で必要な API 権限が正しく申請されているかご確認ください。

* まず、開発者管理画面で API 権限が申請されているかを確認します。

* 組織側の権限付与が完了しているかを確認します:

  * 権限付与組織の管理者をワークスペースに誘導し、手動での権限付与を完了させます。
  * もしくは、統一権限付与スイート SDK を統合し、自動化された権限付与フローを実現します。

OpenAPI の呼び出しで 403 が返される場合、アプリの権限付与組織がアプリに権限を付与していないか、または組織が以前にアプリに付与した権限を解除したことを示します。

### 権限付与コンポーネントの統合には開発時間が必要です。開発者が権限付与コンポーネントの統合に間に合わない場合はどうすればよいですか？403 問題を解決する暫定的な対策はありますか？

回答：サードパーティアプリの開発者は、**権限付与組織の管理者**をワークスペースに誘導し、手動での権限付与を完了させることができます。