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"

액세스 토큰 요청

/api/v1/oauth/token 엔드포인트에 POST 요청 전송하여 클라이언트 ID 와 클라이언트 시크릿을 액세스 토큰으로 교환합니다. 다음 예시 와 같이 자격 증명 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일 또는 만료일 중 먼저 도래하는 날짜까지 유효합니다.

이전 시크릿을 즉시 비활성화하려면 시크릿을 두 번째로 순환하거나 계정을 비활성화합니다. 두 작업 모두 이전 시크릿의 인증을 중지합니다. 손상되었을 수 있는 시크릿을 취소해야 하는 경우 이 중 하나를 사용하세요.

서비스 계정을 비활성화하려면 계정 범위에 대한 엔드포인트에 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"

서비스 계정을 비활성화하면 해당 계정은 더 이상 토큰을 요청 수 없으며 이미 보유하고 있는 토큰은 다음 요청 에서 실패합니다.