認証

すべてのArchyl APIリクエストにはAPIキーによる認証が必要です。このガイドでは、APIキーの作成方法と使用方法を説明します。

APIキーの作成

1. Archylアカウントにログイン
2. プロフィール > APIキー に移動
3. APIキーを作成 をクリック
4. キーを設定:
   • 名前: わかりやすい名前（例: 「CI/CDパイプライン」、「ローカル開発」）
   • 権限: 読み取り専用または読み書き
   • 有効期限: オプションの有効期限
5. 作成 をクリック
6. キーをすぐにコピーして保存してください — 再度表示されません

APIキーの権限

ユースケースに必要な最小限の権限を選択してください。

APIキーの使用

すべてのリクエストに X-API-Key ヘッダーを含めてください:

curl -H "X-API-Key: your-api-key" \
  https://api.archyl.com/api/v1/projects

例: プロジェクト一覧の取得

curl -X GET \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  https://api.archyl.com/api/v1/projects

例: システムの作成

curl -X POST \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payment Service",
    "description": "Handles payment processing",
    "type": "internal"
  }' \
  https://api.archyl.com/api/v1/projects/{projectId}/systems

MCPサーバーの認証

AIアシスタントでMCPサーバーを使用する場合も、認証は同じ方法で行います:

Claude Code / Claude Desktop

MCP設定にAPIキーを追加します:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/sse",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

Cursor

.cursor/mcp.json に設定:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/sse",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

セキュリティのベストプラクティス

キーの保護

• APIキーをバージョン管理にコミットしない
• CI/CDパイプラインでは環境変数を使用する
• キーを定期的にローテーションする
• 環境ごとに別のキーを使用する

環境変数

# .env に保存（.gitignore に追加）
ARCHYL_API_KEY=your-api-key

# スクリプトで使用
curl -H "X-API-Key: $ARCHYL_API_KEY" \
  https://api.archyl.com/api/v1/projects

CI/CD連携

CI/CDプラットフォームにAPIキーをシークレットとして保存します:

GitHub Actions:

- name: Update Architecture
  env:
    ARCHYL_API_KEY: ${{ secrets.ARCHYL_API_KEY }}
  run: |
    curl -X POST \
      -H "X-API-Key: $ARCHYL_API_KEY" \
      https://api.archyl.com/api/v1/projects/$PROJECT_ID/discover

GitLab CI:

update-architecture:
  script:
    - curl -X POST -H "X-API-Key: $ARCHYL_API_KEY" https://api.archyl.com/api/v1/projects/$PROJECT_ID/discover

APIキーの管理

キーの確認

プロフィール > APIキー で有効なキーをすべて確認できます:

• キー名と作成日
• 権限レベル
• 有効期限の状態
• 最終使用日時

キーの失効

漏洩した、または不要なキーを失効させるには:

1. プロフィール > APIキー に移動
2. 失効させるキーを見つける
3. 失効 をクリック
4. 操作を確認

失効したキーは即座に無効化されます。

キーの有効期限

キーには有効期限を設定できます:

• 無期限: 手動で失効するまで有効
• 30日: 一時的なアクセスに適切
• 90日: セキュリティと利便性のバランス
• カスタム: 任意の有効期限を設定

エラーレスポンス

無効または欠落したキー

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

HTTPステータス: 401 Unauthorized

権限不足

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have write permissions"
  }
}

HTTPステータス: 403 Forbidden

期限切れキー

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key has expired"
  }
}

HTTPステータス: 401 Unauthorized

次のステップ

• API概要 - 完全なAPIドキュメント
• MCPサーバー - AIアシスタント連携