Same-email association

An external app can request that its signed-in user be associated with a HALO Access Identity using the same email. The user approves in both the partner app and HALO. Email equality alone never links accounts or grants Tools. This optional flow is part of Agent Access.

#Consent flow

1. 1
   Obtain partner consent

   Explain the HALO identity association, obtain the signed-in user's consent, and save a real consent receipt, timestamp, and policy version on the partner server. Use an email the partner has verified.

2. 2
   Verify the HALO owner

   Create a Link with emailLink. The user signs in to the matching HALO account and explicitly approves the association on HALO's Link page.

3. 3
   Complete separate Tool consent

   Continue the Tool/resource review and missing Connected Account authorization. Final Client App Tool consent is still required before Client Access is issued.

#Email association request

Add the following top-level emailLink field to the full Link creation body in the partner guide. It is supported only for endUser.type external. Omit it for project_auth users. Authenticate creation with the Project server API key.

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

The example timestamp is illustrative. Send the actual timestamp from the saved consent record. approvedAt must be a UTC Z timestamp with seconds and optional one to three millisecond digits, no more than 15 minutes old at creation, and not in the future. receiptId and policyVersion must be nonempty strings of at most 128 characters.

#HALO owner verification

HALO authenticates its own account owner and compares the stored owner email with the partner email after trimming and lowercasing. Dots and plus aliases are not rewritten. An arbitrary partner email or consent flag does not prove HALO account ownership. A mismatch prevents association; an existing link to another Access Identity cannot be replaced by this flow.

The partner should redirect to the returned connectUrl. Project user JWTs and Project publishable keys do not authenticate this HALO owner step. Approval associates the identity; it does not approve Tool access or future write execution.

#Receipt and retry rules

Each receipt can create one Link per Project and Client App. A receipt reused for another Link is rejected. Store the successful session and continue its connectUrl, or retrieve that session from the partner backend. Creation has no receipt lookup or idempotency key.

If a Link expires, obtain fresh user consent and a new receipt. If creation has an unknown outcome and its session cannot be recovered, obtain fresh consent and a new receipt before a new creation. Do not manufacture a receipt or reset a saved consent timestamp to replay it. After the browser returns, use the server verification procedure before accepting Client Access.

#Public response

session.emailLink exposes a masked email, partner consent time/version, and the HALO association approval time. approvedAt is null before HALO approval. The method is same_email. The response does not return the raw email, partner receipt ID, encrypted evidence, or email hash.

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

HALO records partner consent and owner approval separately. Missing or altered evidence prevents association. Successful association leaves the partner's app login and HALO's final Tool consent as separate decisions.