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

# API keys

> マシンやCogno CLIを認証するワークスペース API key を作成、コピー、利用、revokeする手順です。

API keyは、1台のマシン(またはそのマシンのCogno CLI)をbrowser sessionなしでワークスペースに認証させるための鍵です。appで作成し、raw keyを1回だけコピーしてマシンに設定し、不要になったらワークスペース settingsからrevokeします。

## 前提

* keyを作成できるrole — Member、Admin、Ownerのいずれか。Viewerに **設定 → APIキー** は表示されません。
* keyを使うマシンにCogno CLIがインストールされていること。

## API keyの用途

| Use case | Supported |
| - | - |
| `cogno login --token <key>` の認証 | Yes |
| マシンにワークスペースの作業を任せて動かし続ける | Yes |
| マシンでbrowser sessionを使わずに認証する | Yes |
| general public API access | このページでは扱いません |

## Keyを作成する

**1. ページを開く**

Cognoを開き、ワークスペースを選び、**設定 → APIキー** を開きます。

**2. 作成を始める**

**作成** を選びます。**API key を作成** dialogが開きます。

**3. 名前を付ける**

**名前（任意）** に `alice-macbook` や `ci-runner` のような名前を入力し、**作成** を選びます。

**4. すぐにコピーする**

**API key を作成しました** にraw keyとコピーボタン、使用コマンドが表示されます。コピーしてから **完了** を選びます。

> [!WARNING]
>
> raw keyが表示されるのは1回だけです。dialogを閉じた後、Cognoはname、prefix、日付しか表示しません
> — key自体をもう一度読む方法はありません。

## マシンでkeyを使う

作業をさせるマシンで次を実行します。

```bash theme={"system"}
cogno login --token <key>
cogno
```

認証できたかを確認するには次を実行します。

```bash theme={"system"}
cogno doctor
```

**credential** チェックが `workspace API key` と表示し、**backend** がそのkeyで認証されるワークスペースを表示します。

## 一覧の見かた

各行にkeyのidentityと履歴が並ぶので、何をrevokeするかはページを開いたまま判断できます。

| 項目 | 値 |
| - | - |
| 名前 | 作成時に入力した名前、または **名前のないキー**。 |
| Prefix | `cogno_wk_<prefix>...` — keyとマシンを突き合わせるのに使います。 |
| 作成日 | 作成した日付。 |
| 最終使用 | そのkeyが最後に認証に使われた日付(使用後に表示)。 |
| 有効期限 | **無期限**、または期限付きで発行された場合はその日付。 |

管理者とオーナーには一覧の上に切り替えが出ます。**自分のキー** は自分のkey、**すべてのキー** はmember全員のkeyを所有者名つきで表示します。

## Key formatと制限

| Property | Value |
| - | - |
| Prefix | `cogno_wk_` |
| Active key limit | user / ワークスペースごとに25個 |
| Raw key storage | 作成後にraw keyは再表示されません |

## Key名を付ける

revoke判断がすぐできるnameにします。

| Good name | Reason |
| - | - |
| `alice-macbook` | ownerとdeviceがわかる。 |
| `buildkite-prod` | serviceとenvironmentがわかる。 |
| `migration-laptop-2026-06` | temporary useだとわかる。 |

ワークスペースを複数人で運用する場合、`test`、`key`、`machine` のような名前は避けます。

## Keyを保存する

raw keyはpasswordと同じ扱いにします。

* local secret manager、CI secret store、environment variableに保存します。
* task comments、docs、chat、tickets、screenshotsに貼らないでください。
* repositoryにcommitしないでください。
* machineやserviceごとに別keyを作成します。
* 一時的なkeyは作業完了後にrevokeします。

## Keyをrevokeする

**1. keyを見つける**

**設定 → APIキー** を開き、nameまたはprefixでkeyを探します。

**2. 取り消す**

行のゴミ箱アイコン(ラベルは **\<name> を取り消す**)を選びます。行に確認が出ます — 「この key を取り消しますか？使用中のマシンはすぐに access を失います。」 **取り消す** を選びます。

> [!WARNING]
>
> revokeは即時で、取り消しできません。そのkeyを使っているマシンはすぐにaccessを失います。マシンを止めたくない場合は、先にreplacement keyを作成してください。

memberは自分のkeyをrevokeできます。AdminとOwnerは **すべてのキー** からワークスペースのどのkeyでもrevokeできます。

## Keyをrotateする

**1. 新しいkeyを作る**

新しいkeyを作成してコピーします。

**2. マシンに設定する**

マシンで `cogno login --token <new key>` を実行し、保存されているcredentialを差し替えます。

**3. 確認する**

マシンで `cogno doctor` を実行し、**credential** と **backend** が通ることを確認します。

**4. 古いkeyを止める**

**設定 → APIキー** で古いkeyをrevokeします。

## Troubleshooting

| Symptom | Check |
| - | - |
| raw keyを閉じてしまった | 新しいkeyを作成します。既存のraw keyは再表示できません。 |
| keyの作成が失敗する | このワークスペースの自分のactive keys数を確認します。limitは25個です。 |
| **APIキー** が設定に出てこない | そのroleではkeyを作成できません。Viewerにはページが表示されません。 |
| マシンが認証されない | そのマシンで `cogno doctor` を実行します。**credential** と **backend** が原因を示します。 |
| revoke後にマシンが止まった | そのマシン用に新しいkeyを作成し、`cogno login --token <key>` でログインし直します。 |

ここにない症状は [Troubleshooting](/docs/ja/troubleshooting.md) を参照してください。

## Related docs

* [トラブルシューティング](/docs/ja/troubleshooting.md)
* [自社サーバーでCognoを動かす](/docs/ja/remote-servers.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.