# Registered-client participation and introductions

**Deployed implementation preview. Activation is disabled pending trusted
owner-device and registered-client acceptance.** This guide describes the candidate v1 API, not a
newly enabled customer service. The separate Data Vault file flow on the existing `hybrid-mainnet` infrastructure retains
its existing availability and authorization.

The existing network identifier does not establish activation of the separately developing Hybrid Protocol Mainnet or its proposed native mechanisms.

Build your own application interface on this generic API. A conference is the
reference use case; the endpoint contains no client-specific brand, source data
provider or matching marketplace dependency.

## 1. Responsibilities and prerequisites

| Component | Responsibility |
| --- | --- |
| Hybrid ID | Existing owner identities, client registration, current owner/agent authority and exact owner-device decision receipts. |
| Core / Data Vault | Canonical encrypted files, protection, storage, receipts and authoritative storage usage. |
| Cortex | Scoped participation projections, bounded matches, mutual introduction review, recovery/status and observation metering. |
| Your application | Its interface, owner-device review, protected backend and business-specific ingestion/matching experience. |

Register the actual production HTTPS origin and exact same-origin callback under
the existing Hybrid ID client contract. Staging is a separate registration.
Complete real owner account/protection setup through the existing owner-device
API. Keep passwords, native sessions, authenticator material and private owner
keys on that device. Do not use the synthetic account driver's automatic approvals
as a customer consent interface.

The platform must admit your exact registered client. The implemented capability connection and owner-decision
issuance are tracked in
[Hybrid ID issue 12](https://github.com/Hybrid-Chain/hybrid-id-sso-website/issues/12).
Ordinary sign-in, file-read scope and the existing local responder credential do
not grant the new platform permissions. There is no replacement Cortex app key.
Business/team Vaults and unlimited background authority are outside this slice.

## 2. Authentication and request format

Candidate endpoints:

- `GET https://hybrid-cortex.com/api/platform/v1/status`: admission status only.
- `POST https://hybrid-cortex.com/api/platform/v1`: one versioned operation.
- [OpenAPI](/integrations/cortex-platform-v1.openapi.json).
- [Backend Node SDK](/integrations/cortex-platform-node.mjs).
- [Internal authority response](/integrations/platform/identity-authority.schema.json).
- [Synthetic canonicalization/interop vector](/integrations/platform/interop-vector.json) (not a live grant or credential).

The backend uses registered-app HTTP Basic and the purpose-scoped owner's or exact
agent's connection in `access_token`. Sensitive owner decisions additionally
require `approval_token` from the canonical owner-device review. Browsers, cookies
and Origin-bearing requests are rejected; use your own protected backend.

```json
{
  "access_token": "<purpose-scoped Hybrid ID connection>",
  "operation": "participation.approve",
  "request_id": "<persisted UUID>",
  "approval_token": "<exact owner-device decision from Hybrid ID>",
  "input": {
    "space": "<space UUID>",
    "purpose": "professional-introductions",
    "agent": "<existing owner-controlled Cortex agent profile UUID>",
    "revision": 0,
    "expires_at": 1792627200000,
    "offers": ["identity-integration"],
    "seeks": ["event-operations"],
    "disclosure": {
      "display_name": "<owner-reviewed display name>",
      "headline": "<owner-reviewed role>",
      "contact": "<owner-approved contact destination>"
    },
    "reviewed": true
  }
}
```

The example expiry is illustrative; use an actual future UTC millisecond timestamp
within the current space. A client-supplied `reviewed: true` never substitutes for
the exact owner-device receipt. Agent binding, participation approval/withdrawal,
space archive and introduction decisions require those receipts. Neither an agent
nor the application backend can manufacture one.

Responses bind `schema`, `request_id` and `result`. Preserve exact inputs and
request IDs outside source control. A retained mutation receipt is not necessarily
the current resource state; read its status after an uncertain result. Sensitive
contact cards are never stored in the retry ledger.

## 3. Backend SDK and owner review

Use Node on the application's backend. Store credentials in protected runtime
configuration, never browser bundles, source control, CLI arguments or logs.

```javascript
import {readFileSync} from 'node:fs';
import {CortexPlatformClient, preparePlatformReview}
  from './cortex-platform-node.mjs';

// A private, owner-only file outside source control.
const config = JSON.parse(readFileSync(process.env.PLATFORM_CONFIG, 'utf8'));
const client = new CortexPlatformClient({
  clientId: config.clientId,
  clientSecret: config.clientSecret,
  accessToken: config.accessToken
});

const operation = 'participation.approve';
const requestId = config.retainedRequestId; // Generated and persisted BEFORE owner review.
const input = config.ownerReviewedParticipation;
const preview = preparePlatformReview(config.clientId, operation, input, requestId);
// Show preview.request to the owner on their device as DATA, not instructions.
// Obtain the exact decision from the trusted owner-device flow below.
// This backend helper cannot sign in, obtain a factor or approve for the owner.
const result = await client.call(operation, input, {
  requestId,
  ownerApproval: config.exactOwnerApprovalToken
});
```

The digest is SHA-256 of canonical JSON `{client_id, operation, request_id, input}`:
recursively sorted object keys, array order preserved, normal JSON scalar encoding.
The owner device must review the full preimage, not approve an unexplained hash.
Tokens and Basic credentials are excluded from that preimage and all durable
Cortex workflow/monitoring logs. A receipt is bound to one exact request. Renewing
legitimate authentication must not change its content or IDs.

### Trusted owner-device connection and exact decisions

Hybrid ID's reviewed implementation is [provider PR 14](https://github.com/Hybrid-Chain/hybrid-id-sso-website/pull/14),
revision `677351a54f885c94387ff96f6b63191ae8034a14`, with native Identity
[PR 173](https://github.com/Hybrid-Chain/hybrid-identity-server/pull/173), revision
`d5ebb00ae35f269d00d2696bc61c3e57b2ad7cf9`. Both are merged and deployed with
all new gates disabled: provider `2417190`, native `7ead697`.
[Closed-gate deployment receipt](https://github.com/Hybrid-Chain/hybrid-id-sso-website/blob/537da28/docs/evidence/cortex-platform-authority-12-deployment.json).
No client was admitted and no credential issued. Cortex is also deployed with
activation disabled; genuine owner/client commissioning remains open.
[Exact owner API and recovery contract](https://github.com/Hybrid-Chain/hybrid-id-sso-website/blob/677351a54f885c94387ff96f6b63191ae8034a14/docs/cortex-platform-authority-v1.md).
The capability permission strings are separate connection permissions, not newly
registered OAuth scopes. Existing SSO, responder and file scopes are unchanged.

Use the reviewed [owner-device Node SDK](https://github.com/Hybrid-Chain/hybrid-id-sso-website/blob/677351a54f885c94387ff96f6b63191ae8034a14/public/integrations/hybrid-id-cortex-owner-node.mjs)
on a trusted owner device. It calls the deployed, disabled endpoint directly:
`POST https://auth.hybrid-id.com/cortex/platform/owner`, JSON with the original
native `hcb_` source bearer. This API rejects cookies and browser Origin headers;
it is not a Cortex browser fetch or partner backend proxy. The SDK does not
provide sign-in or a completed human review screen. Implement and validate the
actual trusted device's display and explicit choice before commissioning.
Passwords, native sessions, authenticator codes and step-up tokens stay on that
device and never enter Cortex, the partner backend, logs or chat.

1. Call `connectionPreview({clientId, permissions, callerKind, agentId, expiresIn})`.
   Display the returned application/name/origin, Cortex audience, explicit
   permissions, owner versus delegated-agent role, selected personal native agent,
   internal owner projection, service-only current-participant checks and exact
   expiry. A selected agent is required before binding/participation; null is only
   preliminary onboarding. An agent connection cannot approve owner decisions.
2. After the owner's explicit choice, obtain a fresh one-use authenticator step-up
   from the existing native owner security API, directly from that same device:

```text
POST https://api.hybrid-chain.com/api/v2/security/step-up
Authorization: Bearer <same original native source session>
Content-Type: application/json
```

```json
{"purpose":"CORTEX_PLATFORM_APPROVAL","authenticator_code":"<current owner code>"}
```

3. Call `approveConnection(preview, {stepUpToken,
   acknowledgement: 'CONNECT_CORTEX_PLATFORM'})`. Only the returned scoped
   `hccp_connection_...` token belongs with the registered application's backend
   client. Preserve the returned grant, selected agent and fixed deadline. The
   owner source and factor are never forwarded. There is no automatic refresh.
4. For a sensitive operation, retain its original `{operation, request_id, input}`.
   Call `decisionPreview(grantId, request, review)` on the owner device. This
   request omits `client_id` because the selected grant already binds it; display
   and verify the returned app and complete original operation, not just a hash.
   Use `review: null` except for an introduction decision, where the exact input is:

```javascript
const review = {
  terms: currentIntroduction.review.terms,
  your_contact_card: currentIntroduction.review.your_contact_card
};
```

5. Display those exact terms, purpose, recipient alias, card and expiry; obtain the
   owner's explicit decision and another fresh `CORTEX_PLATFORM_APPROVAL` step-up.
   Call `approveDecision(preview, {stepUpToken,
   acknowledgement: 'APPROVE_EXACT_CORTEX_DECISION'})`. Send only its transient
   `approval_token` with that same backend request. Reusing a different input,
   request ID, operation, owner or connection fails. Reply auto-approval does not
   replace any owner decision here.

Identical approved-preview retries recover the same connection or exact decision
until the original deadline; they do not extend it or consume a new factor after
a saved successful receipt. An uncertain result without a saved receipt may need
a fresh factor against that same preview. Never fabricate an approval.
`connectionStatus`, owner-only `connections` and `revokeConnection` use the owner
SDK directly. Source withdrawal remains available after a protection change and
stops later access; prior disclosures cannot be recalled.

An expired or changed source, protection/key revision or selected agent needs a
new explicit connection. Preserve original Cortex resources and request receipts;
re-approve the current participation revision with the new grant. A new grant must
not silently replace the generation on old participation or resurrect its old
queries/introductions. Client and genuine owner-device acceptance remain separate
from synthetic SDK/HMAC tests.

### Prepare client admission and genuine owner acceptance

Cortex source is deployed with activation disabled. Before registration/admission,
complete the [client intake template](https://github.com/Hybrid-Chain/hybrid-cortex-website/blob/main/docs/platform-client-admission.template.json)
and follow the [commissioning flow](https://github.com/Hybrid-Chain/hybrid-cortex-website/blob/main/docs/platform-client-commissioning.md).
Provide the exact HTTPS application origin/callbacks, operational contact, trusted
owner-device presenter, proposed purpose, selected-agent flow and retention/support
requirements. Keep unknowns empty and secrets out of the intake. This does not
admit a client or activate the platform. A browser-only interface cannot use the
owner API directly; the trusted-device presenter and genuine owner choices need
separate acceptance.

## 4. Resume onboarding and bind an existing agent

1. Call `onboarding.begin` with `{}` and a retained request ID. Repeating it returns
   the same checkpoint for this app/owner.
2. Read `onboarding.status` with `{id}`. Its `steps` report canonical identity,
   protection, personal Vault and selected-agent readiness; `next` names the next
   incomplete step. Resolve native setup directly through Hybrid ID.
3. With an exact owner decision, call `onboarding.bind-agent` with
   `{id, revision, agent}`. `agent` is an existing owner-controlled, linked personal
   Cortex profile, not a new identity or caller-chosen native principal.
4. Read status again. `ready` does not start inference, publish a profile, grant
   knowledge, enroll an organization or authorize spending.

If the owner has an existing Hybrid ID agent but no Cortex profile, use
`onboarding.register-agent` with `{id, revision, native_agent, name, role}` and an
exact owner decision. `native_agent` is the canonical personal agent selected in
Hybrid ID; `name` and `role` are the owner's reviewed Cortex presentation. The
current canonical ownership and personal representation are checked. An existing
link/profile is reused; otherwise one private Cortex profile is prepared. Native
identity and keys are preserved, and public network membership/publication and
responder execution remain separate. New native agents are created through
Hybrid ID's accepted owner flow, not this Cortex operation.

The API does not create account passwords/protection keys or import a provider's
entire dataset. Imported records, provisioned accounts, activated owners and
explicitly authorized Vaults remain separate onboarding states.

## 5. Create a bounded introduction space

An admitted organizer calls `space.create` with:

```json
{
  "name": "<conference or other private introduction space>",
  "purpose": "professional-introductions",
  "expires_at": 1792627200000
}
```

Use `space.status` to inspect an authorized space. The initial safety bound is a
future expiry within 30 days, not a priced allowance or indefinite delegation.
`space.archive` requires `{space, revision}` and an exact organizer decision.
Archiving prevents subsequent matching/disclosure. No organizer acquires access
to attendee contact cards or private knowledge by creating a space.

## 6. Approve participation and run a bounded query

Each owner separately approves the exact payload in section 2, including the
explicit purpose text. Cortex rejects a purpose that differs from the immutable
space purpose, even if a client supplied a valid receipt for that different text.
Topic codes are a
small, deliberate participation projection, not a raw personal dataset. Core has
confirmed that this manual flow requires no Core changes or new file, processing
or storage permission. It does not read native Vault files. Hybrid ID authority
and exact owner-decision acceptance remain required. Later automatic Vault-derived
projections require a separate purpose-bound authorization/runtime-read contract;
existing file, verification, archive and recovery grants cannot substitute. Cortex
seals the projection and proposed contact card at rest with authenticated
app/space/owner/revision binding. This is server-side application encryption,
not owner-held end-to-end encryption or private computation on ciphertext.

An authorized participant calls `participation.discover` with `{participant}`.
It returns currently authorized space-local aliases and an optional `next`
cursor. Pass `after: next` for the next page. No names, features, contact cards,
profile counts or running-responder claims are returned.

```json
{"operation":"query.match","input":{"requester":"<your alias>","target":"<another opted-in alias>"}}
```

Add the standard authentication and retained request ID. The engine returns only
`eligible`, `match_band` (`no-match`, `possible-fit`, `strong-fit`), fixed
`reason_codes` and the rule-engine version. It compares offered/requested topic
codes; it produces no inferred qualifications, percentage accuracy claim or
freeform model answer. It accepts no arbitrary attribute filters or prompt.

`query.status` takes `{query}`. Both canonical grants, protection/agent bindings,
participation versions, expiry and current membership are rechecked before use.
Outages fail closed. Repeated equivalent pairs/versions reuse the query; new
request IDs do not create duplicate query units. Replaying an old operation after
its reviewed participation basis changes cannot resurrect the old result.

## 7. Obtain mutual introduction approval

1. The requester calls `introduction.request` with `{query}`. The state is
   `awaiting-approval`, not delivered or accepted.
2. Each owner calls `introduction.status` with `{introduction}`. `review` contains
   that owner's proposed card, recipient alias, purpose, expiry, complete `terms` preimage and `terms_digest`.
3. Each owner reviews those exact terms on their own device, obtains a separate
   canonical approval, then submits:

```json
{
  "introduction": "<introduction UUID>",
  "decision": "approve",
  "reviewed": true,
  "terms_digest": "<your current review digest>"
}
```

Use `introduction.decide` and its exact owner approval token. A `decline` ends the
request. Reply auto-approval never covers either owner's decision.

4. After both approvals, `introduction.disclose` with `{introduction}` returns
   only the approved counterparty card to the authorized participant. Repeat it
   only under current authority; previously copied information cannot be recalled.
5. `participation.withdraw` with `{participant, revision}` and an exact owner
   decision stops future use. App/source revocation, protection changes, expiry,
   agent relinking and space archive also stop subsequent authorized disclosure.

`conversation_delivery: "not-requested"` is deliberate: accepting an introduction
has not sent a message, created an encrypted topic, started a responder or made a
payment. A client may separately use the existing signed mailbox and approved
reply protocol; report that operation's actual status. Never impersonate an agent
or treat introductions as approval to expose earlier history.

## 8. Sync, metering and monitoring

Owner-only `sync` takes `{}` initially, then `{cursor: previous.next}`. Its opaque
cursor binds this app/owner and hides global event sequence numbers. Events carry
only kinds, resource IDs and times. Read current resource status before acting;
a notification is not a grant or a delivery receipt. Exact-agent clients use
known scoped query/introduction status reads; they cannot enumerate all owner
activity through this owner endpoint.

Owner-only `usage` takes `{}` and returns observation counters, recorded agent
bindings, projection ciphertext bytes and sanitized request outcome/latency
buckets. The figures do not count running models, canonical Vault storage,
verified humans, money owed, invoices, payments or replica capacity. Stable retries
and equivalent query/introduction operations do not multiply their usage units.
Canonical storage usage requires a separate supported Core consumer contract.
Current quota accounting includes incomplete uploads; immutable registrations
and completion receipts alone do not supply an owner/app-bound billing stream.
The future contract must distinguish reserved from committed logical ciphertext
bytes, deduplicate original objects across retries/replicas, define lifecycle,
retention/cursors/reconciliation and use trusted private-provider app attribution.
Quota totals and Explorer summaries are not billable-storage totals. This later
consumer gap does not block manual participation; financial charging stays off.

The service also records operation/outcome/latency totals without owner or client
identifiers, including authority failures before an owner can be authenticated.
Private operational monitoring is separate from this client API. Usage observations are not charges or proof of uptime.

## 9. Errors, testing and acceptance

| Status | Handling |
| --- | --- |
| 400 / 415 | Correct invalid fields, review terms, content type or forbidden browser context. |
| 401 | Obtain legitimate fresh authentication and retain operation IDs/content. |
| 403 | Authority is denied, withdrawn, changed, unadmitted or lacks exact owner approval. Never silently restore it. |
| 404 | Resource unavailable in this app/owner/agent scope. |
| 409 | State/revision/content conflict. Reconcile the original request before changing IDs. |
| 413 / 429 | Respect body and temporary safety limits; these are not purchased allowances. |
| 503 | Feature disabled or current dependency unavailable; no stale-success authorization. |

Before requesting client access, verify authentication, exact owner approvals, original-operation retries, expiry and revocation with the integration team. This reference does not activate the API.