Agent Access 연동

MIKA 같은 파트너 앱은 자체 회원가입을 유지하면서 HALO Agent Access로 Calendar 또는 Drive Tool을 요청할 수 있습니다. HALO는 Access Identity 소유자를 확인하고, 부족한 Connected Account 권한에 대한 동의를 받은 뒤, 최종 Tool 동의가 완료되면 Client Access를 발급합니다.

#회원가입과 Access

파트너가 자체 로그인을 사용한다면 Identity OAuth Client는 선택 사항입니다. 이를 등록해도 Calendar나 Drive Tool 권한은 부여되지 않습니다. Project Authentication 로그인으로 Access Identity를 소유한 HALO 계정에 로그인되는 것도 아닙니다. 앱 회원가입과 JWT는 프로젝트 인증 문서에서 확인하세요.

#Client App 설정

파트너 계정 소유의 Project와 Service를 생성하세요. Project의 Agent Access 탭에서 해당 Service를 Client App으로 설정합니다. 필수·선택 Tool, 명시적인 리소스 선택자, 정확한 HTTPS Return URL을 저장하세요. Connected Account OAuth 클라이언트는 HALO가 관리하므로 여기에서 파트너의 Google 클라이언트 비밀을 등록하지 않습니다.

#Link 생성

파트너 백엔드에서 로그인한 사용자의 고정된 내부 ID로 Link를 생성하세요. 이메일을 사용자 ID로 사용하거나 브라우저가 다른 사용자의 ID를 선택하도록 허용하지 마세요. 필수 Tool은 저장한 매니페스트와 일치해야 하고, 리소스는 매니페스트의 선택자 범위에 포함되어야 합니다. 빈 선택자는 리소스 접근을 허용하지 않습니다.

curl -X POST \
  https://api.agihalo.com/api/v1/agent-access/projects/PROJECT_KEY/link-sessions \
  -H "Authorization: Bearer $HALO_PROJECT_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clientAppId": "SERVICE_UUID",
    "endUser": { "type": "external", "externalUserId": "partner-user-123" },
    "requiredTools": [{
      "agentId": "google-calendar",
      "toolId": "calendar.event.read",
      "resourceSelectors": [{ "type": "calendar", "ids": ["primary"] }]
    }],
    "optionalTools": [],
    "returnUrl": "https://app.example.com/halo/complete",
    "state": "SERVER_GENERATED_RANDOM_STATE"
  }'

HALO Project Authentication 사용자라면 endUser 객체를 다음과 같이 바꾸세요. HALO가 선택한 Project에 대한 JWT를 검증합니다.

{
  "type": "project_auth",
  "accessToken": "PROJECT_USER_ACCESS_TOKEN"
}

응답에는 connectUrl과 session.id가 포함됩니다. 리디렉션 전에 요청을 시작한 파트너 사용자, 세션 ID, state, 연결 URL, 만료 시각을 백엔드에 저장하세요. Link Session의 유효 시간은 15분입니다. 외부 사용자는 선택적으로 동의를 받은 뒤 동일 이메일 연결을 요청할 수 있습니다.

#복귀 결과 검증

1. 1
   HALO Link 완료

   사용자가 HALO에 로그인해 Tool과 리소스를 검토하고, 부족한 Connected Account 권한을 승인한 뒤 최종 Tool 동의를 완료합니다. 기존 공급자 권한이 충분하면 공급자 리디렉션을 생략할 수 있지만 최종 동의는 필요합니다.

2. 2
   콜백 검증

   Return URL로 halo_link_session, halo_link_status, state가 전달됩니다. 저장한 요청과 요청을 시작한 사용자를 기준으로 state를 검증하고, 반환된 세션 ID가 저장한 ID와 같은지 확인하며, state 재사용을 차단하세요. 브라우저에 표시된 상태만으로 성공을 판단할 수 없습니다.

3. 3
   백엔드에서 세션 조회

   아래 엔드포인트에 Project 서버 키와 저장한 세션 ID를 사용하세요. 해당 사용자의 권한을 저장하기 전에 session.status가 completed이고 session.clientAccessId가 null이 아닌지 확인하세요. 브라우저가 전달한 clientAccessId는 받아들이지 마세요.

#실행과 승인

{
  "clientAccessId": "STORED_CLIENT_ACCESS_UUID",
  "agentId": "google-calendar",
  "toolId": "calendar.event.read",
  "input": { "calendarId": "primary" },
  "idempotencyKey": "UNIQUE_PARTNER_OPERATION_ID"
}

HALO는 Client Access, 허용된 Tool과 리소스, Connected Account 상태, 실행 승인을 검사합니다. 읽기 권한으로 쓰기를 수행할 수는 없습니다. 쓰기 Tool은 먼저 approvals 엔드포인트에 동일한 clientAccessId, agentId, toolId, input, idempotencyKey를 제출하세요.

응답에는 approval.approvalId가 포함됩니다. 소유자는 HALO /access-identity에서 승인합니다. 승인 후 해당 approvalId와 동일한 입력 및 멱등성 키로 실행하세요. 파트너가 소유자를 대신해 승인할 수는 없습니다. 대기·거절·만료 상태의 승인이나 입력이 변경된 승인은 실행을 허용하지 않습니다.

HTTP 200에서도 execution.status를 확인하세요. reconciliation_required 결과는 HTTP 202를 반환합니다. 결과를 알 수 없는 작업을 새 작업 ID로 재시도하지 말고 실행 이력을 조회하세요. Link 생성과 Tool 실행은 재시도 규칙이 다릅니다.

#접근 권한 철회

파트너 백엔드에서 Client Access를 철회할 수 있습니다. 소유자도 HALO /access-identity에서 철회할 수 있습니다. 철회하면 이후 승인과 실행이 차단되며 감사 이력은 유지됩니다. 재연결하려면 새 Link를 요청하세요. 파트너 서비스의 회원 계정은 별도로 유지됩니다. 공급자의 액세스 토큰과 리프레시 토큰은 전체 흐름에서 HALO 내부에 보관됩니다.