# 認証

APIトークンを作成し、Bearerヘッダーでリクエストを認証します。

Source: https://support.toolingmetrics.com/ja/api/authentication/
Updated: 2026-10-29

**前提条件：** 問い合わせる組織にアクセスできるアカウントが必要です。

<a id="generate-an-api-token"></a>

## APIトークンの作成

APIトークンは個人用です。組織の管理画面ではなく自分のアカウントから作成し、作成者と同じアクセス権を持ちます。

1. サイドバー下部のアバター → **設定**を開き、**APIトークン**タブを選びます。
1. **APIトークンを新規作成**をクリックします。
1. 「CAM Plugin」「ERP Sync」など、連携を識別できる名前を入力します。
1. **作成**をクリックします。トークンは一度だけ表示されるので、すぐにコピーしてください。再表示はできません。

複数のトークンを作成でき、どのトークンも同じ画面から取り消せます。

<a id="authenticate-requests"></a>

## リクエストの認証

各リクエストの`Authorization`ヘッダーにトークンを指定します。

```
Authorization: Bearer <your-token>
```

有効なトークンがない場合は、`WWW-Authenticate: Bearer`ヘッダーを含む`401 Unauthorized`が返されます。

```json
{ "errors": ["Access denied"] }
```

<a id="find-your-organization-id"></a>

## 組織IDの確認

ほとんどのエンドポイントは`organization_id`のパスパラメータを必要とします。次のリクエストで取得できます。

```
GET /v1/organizations
Authorization: Bearer <your-token>
```

レスポンスは組織名とIDの対応表です。

```json
{
  "Acme Manufacturing": 12,
  "Acme Tooling": 15
}
```

以降のリクエストでは、この数値IDを使います。

```
GET /v1/organizations/12/machines
Authorization: Bearer <your-token>
```

<a id="authorization-scoping"></a>

## 権限によるアクセス範囲

正しい組織の有効なトークンがあっても、すべてのレコードが見えるとは限りません。組織内のリソースごとの権限により、範囲がさらに制限されます。

- **サイト管理者**、または対象リソースの**管理者**・**管理担当者**は、組織内の一致するすべてのレコードを見られます。
- 対象リソースの**ユーザー**は、自分が作成したレコード（`user_id`がトークンの所有者と一致するもの）だけを見られます。

この制限はリソースごとに適用されます。例えば`parts`と`machines`の権限は独立しています。書込みだけでなく、すべての一覧・詳細エンドポイントで確認されます。

<a id="error-responses"></a>

## エラーレスポンス

失敗時には次のステータスが返されます。

| ステータス | 意味 |
|---|---|
| `401 Unauthorized` | トークンが未指定・無効、**または**所有者が操作を許可されていない場合。どちらも`403`ではなく`401`です。未指定・無効の場合は`"Access denied"`、権限不足の場合は`"You are not authorized to perform this action"`となります。存在しない`organization_id`は、トークンが届かない組織と同じく権限不足になります。 |
| `404 Not Found` | レコードが存在しない、または別の組織に属する場合。 |
| `422 Unprocessable Entity` | 検証失敗。本文に項目のエラーを含みます。 |

`404`の本文にある形式の不一致を含め、詳細は[エラー](https://support.toolingmetrics.com/ja/api/errors/)を参照してください。