> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/api/ja/preparation/authentication.md).

# API 認証

MaiAgent API の認証方法と API キーの取得方法を説明します

MaiAgent は API キーを使用して認証を行います。

## 認証方法

すべての API リクエストには、HTTP Header に次の形式で API キーを含める必要があります。

```javascript
const headers = {
  "Authorization": "Api-Key YOUR_API_KEY_HERE",
  "Content-Type": "application/json"
}
```

ヘッダーのプレフィックスは `Api-Key` です。`Bearer` ではありません。キーが紐づくメンバー、権限の判定方法、キーが無効になる条件などのルールについては、[API 共通規約：認証](/api/ja/preparation/conventions.md#authentication)を参照してください。

## API キーの取得方法

API キーの取得方法は 2 種類あります。どちらのキーも呼び出し方法は同じです。

* **メンバーによる自己発行**：組織内の有効なメンバーは、管理画面の右上のアバター → <mark style="color:blue;">アカウント</mark> → <mark style="color:blue;">API キー</mark>から、自分用のキーを作成できます。追加の権限は不要です。
* **管理者による代理発行**：「API Key 管理権限」を持つ管理者は、<mark style="color:blue;">組織設定</mark> → <mark style="color:blue;">API Key 管理</mark>で指定したメンバーにキーを発行し、有効期限と 1 分あたりのリクエスト数（RPM）を設定できます。

操作手順は、ユーザーマニュアルの [API Key 管理](https://docs.maiagent.ai/org/developer/api-keys)にある[メンバーによるキーの作成](https://docs.maiagent.ai/org/developer/api-keys#self-issued-keys)と[管理者による API Key の作成](https://docs.maiagent.ai/org/developer/api-keys#create-api-key)を参照してください。

{% hint style="success" %}

* **セキュリティ上の注意**：API キーは適切に保管し、公開の場で共有しないでください
* **キーの形式**：API キーは、プレフィックスとシークレットの 2 つの英数字の部分から構成され、`.` で連結されています。呼び出す際はキー全体を指定してください
  {% endhint %}

{% hint style="warning" %}
キー全体は、作成に成功したときに一度だけ表示されます。その後の一覧には一部の文字のみが表示され、キー全体を再表示したり復元したりすることはできません。保存していなかった場合は、新しいキーを作成して、そのキーを使用するサービスを更新してから、古いキーを失効させてください。
{% endhint %}

## 以前のシステム発行キーが見つからない場合 <a href="#system-issued-api-key" id="system-issued-api-key"></a>

個人アカウントの<mark style="color:blue;">API キー</mark>ページには、自分で作成したキーのみが表示されます。組織に初めて参加したとき（AD 経由の初回ログインを含みます）、システムが有効期限のないキーを自動発行する場合があります。ただし、キー全体の値は提供されないため、そのキーを取得して API を呼び出すことはできません。API を呼び出すには、個人ページで新しいキーを作成し、作成に成功したらすぐにキー全体の値を保存してください。

システムが自動発行したキーや管理者が代理発行したキーについては、組織のキー管理権限を持つメンバーのみが、<mark style="color:blue;">組織キー管理</mark>で所有者、プレフィックス、発行元、状態、有効期限を確認できます。ただし、このページにはキー全体の値は表示されません。この権限がない場合は、組織の所有者または組織のキー管理権限を持つメンバーに、古いキーの確認や失効を依頼してください。

## API キーの権限範囲 <a href="#api-key-permissions" id="api-key-permissions"></a>

API キーで API を呼び出す場合、権限は、その組織におけるキー所有者のロール権限と同じです。必要な権限がない場合、API は 403 Forbidden を返します。

メンバー（members）とロール（groups）の書き込み操作には、<mark style="color:blue;">組織権限</mark>配下のサブ権限である<mark style="color:blue;">組織概要権限</mark>が必要です。組織の所有者はこの制限を受けません。対象となる操作は次のとおりです。

* メンバーの追加：`POST /api/v1/organizations/{organizationPk}/members/`
* メンバーの削除：`DELETE /api/v1/organizations/{organizationPk}/members/{id}/`
* メンバーが所属するロールの変更：`POST /api/v1/organizations/{organizationPk}/members/{id}/update-groups/`
* ロールの作成、更新、削除：`POST` / `PUT` / `PATCH` / `DELETE /api/v1/organizations/{organizationPk}/groups/…`
* ロールのメンバーの一括追加・削除、ロールへの AI アシスタント、受信トレイ、ナレッジベース、データベースの割り当て・解除：`/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-*/…`
* その他のメンバーやロールの書き込み操作（メンバーの一括インポートなど）にも同じ要件が適用されます

{% hint style="info" %}
権限はサブ項目で判定されます。ロール設定で親項目の<mark style="color:blue;">組織権限</mark>が選択されていなくても、配下の<mark style="color:blue;">組織概要権限</mark>が選択されていないとは限りません。403 の原因を調べる際は、管理画面の<mark style="color:blue;">組織設定 → ロール</mark>で<mark style="color:blue;">組織権限</mark>を展開し、キー所有者が所属するロールで<mark style="color:blue;">組織概要権限</mark>が選択されているか確認してください。
{% endhint %}

## エラー処理

認証に失敗すると、API は HTTP エラーコード 401 Unauthorized を返します。

* **API キーの欠落、形式の誤り、または無効なキー**

キーが指定されていない場合、ヘッダーの形式が正しくない場合、キーが無効な場合（存在しない、有効期限切れ、無効化済み、失効済み、または紐づくメンバーが無効化されたか組織から削除された場合）は、すべて同じ内容が返され、どの原因に該当するかは示されません。

```json
{
  "detail": "Authentication credentials were not provided."
}
```

*対処方法：リクエストヘッダーが `Authorization: Api-Key YOUR_API_KEY` になっていること、API キーが完全で、余分なスペースや文字が含まれていないことを確認してください。形式が正しくても失敗する場合は、<mark style="color:blue;">API Key 管理</mark>でキーが無効化、有効期限切れ、失効の状態になっていないことと、紐づくメンバーが引き続き有効であることを確認してください。*

* **`Bearer` の後に API キーを指定した場合**

プラットフォームはログイントークンとして検証するため、異なる内容を返します。

```json
{
  "detail": "Given token not valid for any token type",
  "code": "token_not_valid",
  "messages": [ … ]
}
```

*対処方法：プレフィックスを `Api-Key` に変更してください。*

`401` レスポンスには `WWW-Authenticate` ヘッダーが含まれます。多くのエンドポイントでは、その値は `Bearer realm="api"` です。ステータスコードで判定し、このヘッダーをもとに送信する認証情報の種類を決めないでください。詳細は [API 共通規約：認証失敗時のレスポンス](/api/ja/preparation/conventions.md#auth-errors)を参照してください。キーが有効でも権限が不足している場合は `403` が返されます。上記の [API キーの権限範囲](#api-key-permissions)を参照してください。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/api/ja/preparation/authentication.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.