동일 이메일 연결

외부 앱은 로그인한 사용자를 동일 이메일의 HALO Access Identity에 연결하도록 요청할 수 있습니다. 사용자는 파트너 앱과 HALO 양쪽에서 승인합니다. 이메일이 같다는 이유만으로 계정을 연결하거나 Tool 권한을 부여하지 않습니다. 이 선택적 흐름은 다음 Agent Access 가이드에서 확인할 수 있습니다: Agent Access.

1
파트너 서비스에서 동의 받기
HALO 신원 연결을 설명하고 로그인한 사용자의 동의를 받은 뒤, 실제 동의 기록과 시각, 정책 버전을 파트너 서버에 저장하세요. 파트너가 확인한 이메일을 사용하세요.
2
HALO 계정 소유자 확인
emailLink를 포함해 Link를 생성하세요. 사용자는 이메일이 일치하는 HALO 계정에 로그인하고 HALO Link 페이지에서 연결을 명시적으로 승인합니다.
3
별도의 Tool 동의 완료
Tool과 리소스 검토, 부족한 Connected Account 권한 승인을 진행합니다. Client Access가 발급되려면 Client App에 대한 최종 Tool 동의가 필요합니다.

#이메일 연결 요청

POST/api/v1/agent-access/projects/:projectKey/link-sessions

다음 최상위 emailLink 필드를 Link 생성 본문에 추가하세요. 전체 요청 본문은 파트너 가이드에서 확인할 수 있습니다. endUser.type이 external인 경우에만 지원합니다. project_auth 사용자는 이 필드를 생략하세요. 생성 요청은 Project 서버 API 키로 인증합니다.

{
  "emailLink": {
    "email": "user@example.com",
    "consent": {
      "receiptId": "STORED_PARTNER_CONSENT_ID",
      "approvedAt": "2026-10-12T03:00:00.000Z",
      "policyVersion": "identity-link-v1"
    }
  }
}

예시 시각은 설명용입니다. 저장한 동의 기록의 실제 시각을 전송하세요. approvedAt은 초 단위와 선택적인 소수점 이하 1~3자리 밀리초를 포함하는 UTC Z 시각이어야 합니다. 생성 시점 기준 15분 이내의 시각이어야 하며 미래 시각은 사용할 수 없습니다. receiptId와 policyVersion은 비어 있지 않은 128자 이하 문자열이어야 합니다.

#HALO 계정 소유자 확인

HALO는 자체 계정 소유자를 인증하고, 앞뒤 공백 제거와 소문자 변환 후 저장된 소유자 이메일을 파트너 이메일과 비교합니다. 점이나 플러스 별칭은 변환하지 않습니다. 파트너가 임의로 보낸 이메일이나 동의 표시만으로 HALO 계정 소유권이 입증되지는 않습니다. 이메일이 다르면 연결을 차단하며, 이미 다른 Access Identity에 연결된 관계를 이 흐름으로 교체할 수는 없습니다.

POST/api/v1/agent-access/link-sessions/:linkToken/verify-owner

HALO Link는 소유자 동의 후 HALO 계정 JWT와 명시적인 emailLinkApproved: true를 사용합니다.

파트너는 반환된 connectUrl로 사용자를 이동시켜야 합니다. Project 사용자 JWT나 Project 공개 키로 이 HALO 소유자 확인 단계를 인증할 수는 없습니다. 이 승인은 신원을 연결하는 승인으로, Tool 접근이나 이후 쓰기 실행을 승인하지는 않습니다.

#동의 기록과 재시도 규칙

동의 기록 하나로 Project와 Client App별 Link 하나를 생성할 수 있습니다. 다른 Link에 동일한 기록을 재사용하면 거부됩니다. 생성된 세션을 저장하고 해당 connectUrl에서 계속 진행하거나 파트너 백엔드에서 해당 세션을 조회하세요. 생성 API에는 동의 기록 조회 기능이나 멱등성 키가 없습니다.

Link가 만료되면 사용자의 새 동의와 새 동의 기록을 받으세요. 생성 결과를 알 수 없고 해당 세션도 복구할 수 없다면, 새 Link를 생성하기 전에 다시 동의를 받고 새 기록을 저장하세요. 동의 기록을 임의로 만들거나 저장된 동의 시각을 바꿔 재사용하지 마세요. 브라우저가 돌아온 뒤에는 서버 검증 절차 를 거친 뒤 Client Access를 받아들이세요.

#공개 응답

session.emailLink에는 일부가 가려진 이메일, 파트너 동의 시각과 정책 버전, HALO 연결 승인 시각이 표시됩니다. HALO 승인 전 approvedAt은 null입니다. method는 same_email입니다. 응답에는 원본 이메일, 파트너 동의 기록 ID, 암호화된 증거, 이메일 해시가 포함되지 않습니다.

{
  "method": "same_email",
  "maskedEmail": "u***@example.com",
  "partnerConsent": {
    "approvedAt": "2026-10-12T03:00:00.000Z",
    "policyVersion": "identity-link-v1"
  },
  "approvedAt": null
}

HALO는 파트너 동의와 소유자 승인을 별도로 기록합니다. 증거가 없거나 변경되면 연결을 차단합니다. 연결이 완료되어도 파트너 앱 로그인과 HALO의 최종 Tool 동의는 별도의 결정으로 유지됩니다.

동일 이메일 연결

#동의 흐름

#이메일 연결 요청

#HALO 계정 소유자 확인

#동의 기록과 재시도 규칙

#공개 응답