> ## 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 アプリから API を呼び出す権限を追加申請し、アプリタイプ別の権限管理を実施します

DingTalk のサーバー API を呼び出す前に、必要な API の呼び出し権限を追加する必要があります。アプリ作成後、システムはデフォルトで本人確認とメッセージ通知の API 権限を付与します。アプリにはできるだけ多くの API を活用し、DingTalk のコア機能と全面的に連携することを推奨します。

## 適用対象

* **社内アプリ**：企業が自社で開発し、自社内のみで使用するアプリです。組織内部のシステム統合シーンに適しています。
* **サードパーティ社内アプリ**：ISV（独立系ソフトウェアベンダー）が開発し、複数の企業顧客がインストールして利用するサービス型アプリです。
* **サードパーティ個人アプリ**：プロダクトソリューションプロバイダーの開発者が開発し、DingTalk 上の個人ユーザーに提供するアプリです。

アプリタイプによって、権限申請、承認フロー、API の利用可否に差異がある場合があります。実際のアプリタイプに応じて該当の操作ガイドを参照してください。

## 機能概要

DingTalk のサーバー API を呼び出す前に、必ずアプリに対応する API 呼び出し権限を追加する必要があります。アプリ作成後、システムはデフォルトで一部のベーシック権限を付与します。業務ニーズに応じて必要な API 権限を適切に申請し、DingTalk のコア機能との深い統合を実現することを推奨します。

API 権限は**アプリ単位**で付与され、各アプリ間で権限は相互に独立しています。同一企業の複数のアプリが同じ API を呼び出す必要がある場合でも、各アプリで個別に申請する必要があります。

例：社内に A、B 2 つのアプリが存在し、アプリ A がすでに連絡先の読み取り権限を保有していても、アプリ B が連絡先データにアクセスするには、別途「連絡先」関連の権限を申請する必要があります。操作手順はアプリ A と同様です。

<Warning>
  すべての API を直接有効化できるわけではありません。一部の API は非公開のオープン機能であり、申請を送信して審査に通過してからでないと利用できません。また、一部のプレミアム API は有償または特定の資格要件を伴う場合がありますので、各 API ドキュメントの利用範囲に関する説明を参照してください。
</Warning>

## 前提条件

API 権限を設定する前に、以下の条件を満たしていることを確認してください。

1. アプリタイプが**社内アプリ**、**サードパーティ社内アプリまたはサードパーティ個人アプリ**であり、[開発者バックエンド](https://open-dev.dingtalk.io/)で作成済みであること。
2. 現在ログイン中のアカウントが、該当アプリの管理権限（通常は組織管理者またはアプリ責任者）を保有していること。
3. 企業の認証が完了していること（一部の特殊な API は企業の実名認証完了後にのみ申請可能です）。
4. API 呼び出しの認証に使用するアプリの `AppKey` と `AppSecret` を取得し、適切に設定していること。

## 一般的な API 呼び出し権限の追加

公開されているほとんどのサーバー API に適用され、開発者バックエンドで直接セルフ申請できます。

操作手順：

1. API ドキュメントで、対象 API ドキュメントの権限セクションにある権限スコープをコピーします。

2. [開発者バックエンド](https://open-dev.dingtalk.io/)にログインします。

3. **アプリ開発**ページで、対象アプリをクリックしてアプリ詳細ページに移動します。

4. アプリ詳細ページで**権限管理**をクリックし、コピーした権限スコープを検索して**権限をリクエスト**をクリックします。

## 特殊な API 呼び出し権限の追加

非公開のセンシティブな API や業界専用の API については、DingTalk 側の人手による審査を経てから有効化できます。

操作手順：

1. API ドキュメントで、対象 API ドキュメントの権限セクションにある権限スコープをコピーします。

2. 管理者が[開発者バックエンド](https://open-dev.dingtalk.io/)にログインします。

3. **アプリ開発**ページで、対象アプリをクリックしてアプリ詳細ページに移動します。

4. **権限管理**をクリックし、追加したい特殊な API を選択して**権限をリクエスト**をクリックします。

5. 申請理由を入力し、最後に**申請**をクリックします。

   **説明**

   * API 呼び出し権限の申請は、対応する API の DingTalk 担当者が承認します。承認は通常 1 営業日以内に完了し、承認後はステータスが**有効化完了**に変わります。
   * 申請が拒否された場合、**申請欄**で該当の権限エントリを確認し、**審査未通過**タグにマウスを合わせると具体的な却下理由が表示されます。フィードバックに基づき改善のうえ、再度送信してください。

## 権限不足エラーの解決方法

<Note>
  この解決方法は現時点では新版サーバー API を呼び出す場合のみ適用されます。
</Note>

新版 API を呼び出して `403` エラーが返された場合、レスポンスボディに詳細な権限不足情報が含まれます。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "Code": "Forbidden.AccessDenied.AccessTokenPermissionDenied",
  "StatusCode": 403,
  "Message": "code: 403, この API を呼び出す権限がありません request id: 8197EFxxxx59D33E58",
  "Data": "{\"AccessDeniedDetail\":{\"requiredScopes\":[\"Contact.Org.Read\"]},\"Code\":\"Forbidden.AccessDenied.AccessTokenPermissionDenied\",\"HostId\":\"dingtalk-inner.aliyuncs.com\",
            \"Message\":\"この API を呼び出す権限がありません\",\"Recommend\":\"https://next.api.aliyun.com/troubleshoot?q=Forbidden.AccessDenied.AccessTokenPermissionDenied\\u0026product=dingtalk\",
            \"RequestId\":\"8197Exxxx88C759D33E58\",\"statusCode\":403}",
  "Stack": null,
  "Description": "\u003cni\u003e",
  "AccessDeniedDetail": {
    "requiredScopes": [
      "Contact.Org.Read"
    ]
  }
}
```

アプリが API を呼び出した際に「この API を呼び出す権限がありません」と返された場合の解決手順：

1. エラーレスポンス内の `AccessDeniedDetail` にある `requiredScopes` フィールドの値を抽出します。これが対象 API に必要な権限スコープ Code です。
2. 現在のアプリの権限管理ページで、その権限スコープ Code を検索し、対応する API 権限の有効化を申請します。

### 重要