Agent Access integration

A partner app such as MIKA can keep its own signup and use HALO Agent Access to request Calendar or Drive Tools. HALO verifies the owner of an Access Identity, obtains missing Connected Account permissions, and issues Client Access after final Tool consent.

#Signup and Access

An Identity OAuth Client is optional when the partner uses its own login. It does not grant Calendar or Drive Tools. Project Authentication login also does not sign the user in to the HALO account that owns an Access Identity. See 项目身份验证 for app signup and JWTs.

#Configure the Client App

Create a Project and a Service owned by the partner account. In the Project's Agent Access tab, configure that Service as the Client App. Save required and optional Tools, explicit resource selectors, and exact HTTPS Return URLs. HALO manages Connected Account OAuth clients; partners do not register Google client secrets here.

#Create a Link

Create the Link on the partner backend using the signed-in user's stable internal ID. Do not use email as the user ID or let the browser choose another user's ID. Required Tools must match the saved manifest and resources must fit its selectors. Empty selectors do not authorize resources.

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"
  }'

For a HALO Project Authentication user, replace the endUser object with the following. HALO validates the JWT for the selected Project.

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

The response contains connectUrl and session.id. Before redirecting, store the initiating partner user, session ID, state, connect URL, and expiry on your backend. Link Sessions last 15 minutes. An external user can optionally request same-email association after consent.

#Verify the return

1. 1
   Complete HALO Link

   The user signs in to HALO, reviews Tools and resources, authorizes missing Connected Account permissions, and confirms final Tool consent. Existing provider permissions can skip a provider redirect; final consent remains required.

2. 2
   Validate the callback

   The Return URL receives halo_link_session, halo_link_status, and state. Validate state against the stored attempt and initiating user, require the returned session ID to equal the stored ID, and handle state replay. Browser status is not proof of success.

3. 3
   Retrieve the session on your backend

   Use the Project server key and stored session ID with the endpoint below. Require session.status to be completed and session.clientAccessId to be non-null before storing authorization for that user. Never accept a clientAccessId from the browser.

#Execute and approve

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

HALO checks Client Access, the granted Tool and resources, Connected Account state, and execution approval. Read permission does not grant writes. For a write Tool, submit the same clientAccessId, agentId, toolId, input, and idempotencyKey to the approvals endpoint first.

The response contains approval.approvalId. The owner approves in HALO /access-identity. Execute with that approvalId and the same input and idempotency key after approval. The partner cannot approve for the owner. Pending, denied, expired, or changed-input approvals do not authorize execution.

Inspect execution.status even for HTTP 200. A reconciliation_required result returns HTTP 202; query execution history instead of retrying an unknown outcome with a new operation ID. Link creation and Tool execution have different retry contracts.

#Revoke access

The partner backend can revoke Client Access. The owner can also revoke in HALO /access-identity. Revocation blocks future approvals and execution and retains audit history. Request a new Link for reconnect; the partner's signup account remains separate. Provider access and refresh tokens stay inside HALO throughout the flow.