APIキーとサービス アカウントの管理

サービス アカウントの作成

このセクションでは、 API、 UI、 agentengine CLI を使用してサービス アカウントを作成する方法について説明します。

プロジェクト スコープのサービス アカウントを作成するには、プロジェクトの PROJECT_OWNER ロールが必要です。

curl -s "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/service-accounts" \
  -X POST \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "my-app-server",
        "description": "Invokes agents from the support app",
        "roles": ["PROJECT_OWNER"],
        "secret_expires_after_hours": 2160
      }'

{
  "client_secret": "ae_sa_sk_...",
  "service_account": {
    "client_id": "ae_sa_id_...",
    "name": "my-app-server",
    "is_active": true
  }
}

curl -s "https://agentengine.mongodb.com/api/v1/organizations/$ORG_ID/service-accounts" \
  -X POST \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "my-app-server",
        "description": "Invokes agents from the support app",
        "roles": ["ORG_GROUP_CREATOR"],
        "secret_expires_after_hours": 2160
      }'

agentengine service-account create my-app-server \
  --project-id $PROJECT_ID \
  --role PROJECT_OWNER \
  --description "Invokes agents from the support app"

アクセス トークンのリクエスト

アクセス トークンのクライアントIDとクライアントシークレットを交換するには、POSTリクエストを/api/v1/oauth/token エンドポイントに送信します。次の例に示すように、認証情報をHTTP基本認証情報 として、またはリクエスト本文の client_id フィールドと client_secret フィールドとして渡します。

curl -s "https://agentengine.mongodb.com/api/v1/oauth/token" \
  -X POST \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials"

grant_typeフィールドはclient_credentials 値のみを受け入れます。応答は、次の出力のようになります。

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600
}

アクセス トークンの有効期間は 1 時間です。現在のトークンの有効期限が切れる前に新しいトークンをリクエストします。 Atlas Agent Engine は、各サービス アカウントのトークンリクエストのレートを制御し、クライアントがトークンをリクエストしすぎる場合は 429 エラーコードを返します。

アクセス トークンを使用したエージェントの呼び出し

アクセス トークンを使用してエージェントを呼び出すには、 呼び出しリクエストの Authorization ヘッダーにアクセス トークンを送信します。

curl -s "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/invoke" \
  -X POST \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, agent!"}'

プロジェクト スコープのサービス アカウントは、自分のプロジェクトでのみ機能できます。リクエストパスが他のプロジェクトを指定する場合、Atlas Agent Engine はそのリクエストを拒否します。組織スコープのサービス アカウントは、自分の組織内のプロジェクトに名前を付ける必要があります。

ORG_GROUP_CREATOR ロールだけでは、組織内のすべてのプロジェクトへのアクセス権が付与されるわけではありません。 ORG_GROUP_CREATOR ロールを持つ組織スコープのサービス アカウントは、Atlas Agent Engine が管理するプロジェクトでのみエージェントを呼び出すことができます。 Atlas ベースのプロジェクトでエージェントを呼び出すには、PROJECT_OWNER ロールを持つプロジェクトスコープのサービスアカウントを使用します。

サービス アカウントのローテーションと非アクティブ化

サービス アカウントのシークレットを置き換えるには、アカウントのスコープのローテーション エンドポイントに POSTリクエストを送信します。プロジェクト スコープのアカウントには、次のエンドポイントを使用します。

curl -s "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/service-accounts/$CLIENT_ID/rotate" \
  -X POST \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"secret_expires_after_hours": 2160}'

組織スコープのアカウントには、次のエンドポイントを使用します。

curl -s "https://agentengine.mongodb.com/api/v1/organizations/$ORG_ID/service-accounts/$CLIENT_ID/rotate" \
  -X POST \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"secret_expires_after_hours": 2160}'

secret_expires_after_hoursフィールドは任意で、デフォルトは 2160 時間です。デフォルトのを受け入れるには、リクエスト本文を省略します。応答は作成応答と同じ形式で、新しいシークレットが含まれます。以前のシークレットは、最大 7 日間、または独自の有効期限が切れるまで有効のままです。

以前のシークレットをすぐに非アクティブ化するには、シークレットを再度ローテーションするか、アカウントを非アクティブ化します。どちらのアクションも、前のシークレットの認証を停止します。侵害される可能性のあるシークレットを取り消す必要がある場合は、これらの 1 つを使用します。

サービス アカウントを無効化するには、アカウントのスコープのエンドポイントに DELETEリクエストを送信します。プロジェクト スコープのアカウントには、次のエンドポイントを使用します。

curl -s "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/service-accounts/$CLIENT_ID" \
  -X DELETE \
  -H "Authorization: Bearer $SESSION_TOKEN"

組織スコープのアカウントには、次のエンドポイントを使用します。

curl -s "https://agentengine.mongodb.com/api/v1/organizations/$ORG_ID/service-accounts/$CLIENT_ID" \
  -X DELETE \
  -H "Authorization: Bearer $SESSION_TOKEN"

サービス アカウントを非アクティブ化すると、そのアカウントはトークンをリクエストできなくなり、すでに保持しているトークンは次のリクエストで失敗します。