# One SDK, three cumulative integration tiers

Use one consolidated server SDK and the shared browser controller. Choose a
recipe for the capability you need; adding the next tier does not replace your
SDK or session integration. These are integration levels, not pricing plans or
three different authentication systems.

| Tier | Adds | Your application supplies |
| --- | --- | --- |
| 1 | Keyring connection session and permitted insights | Meaningful insight values and the application behavior that uses them |
| 2 | Rights invitations and protected action challenges | Rights policy, resource identifiers, approved-action handler |
| 3 | Account-specific sign-in | Account ownership verification, private account mapping, app login session |

Start with the [company integration walkthrough](/developers/api/#first-integration)
for downloadable route code and task examples for sessions, QR display and site
observations. Use the tiers below to choose the next capability.

## Tier 1: sessions and insights

Your product contribution is the insight: an expressed preference, confirmed
purchase or other meaningful observation that can improve personalization. Choose
what is useful and permitted to record, then supply those values through the
registered insight fields. “Trusted” means the values come from a source your
application can substantiate; it does not mean sending a generic stream of clicks.

Remembering the connection is Mementom SDK/framework wiring, not a partner
responsibility. Partners do not provide session storage. The SDK’s encrypted
HttpOnly cookie helper already supports carrying the connection; the complete
framework must own its session lifecycle and temporary request/callback state.
No new customer or keyring database is required. Today the low-level SDK and
[Node route example](/developers/examples/company-connection.mjs) supplies the
same-browser connect, callback/cancel, status and logout wiring. Complete framework
adapters and an external-company phone-to-desktop relay remain to be delivered.

1. Register your website and server callback in the developer console. Start
   with account access off. Run the generated setup to register your public RSA
   key and prepare the connection challenge. The API calls this challenge Login;
   it does not require a customer account in your system.
2. Your backend starts a connection request and saves its random state, request
   ID, response destination, expiry and browser binding. Start with the supplied
   same-browser redirect. Harbor’s cross-device QR uses a separate relay; encoding
   a normal connection URL does not connect the original desktop visit.
3. The keyring completes the service-issued authorization. Your backend validates
   the return and exchanges the code once. It retains the resulting session in
   server-owned storage or an encrypted HttpOnly cookie. The requesting UX reads
   your own status endpoint so it knows which visit is connected.
4. Mementom maps that session to the completing keyring internally. Your backend
   calls `mementom.forSession(sessionId).insights.ingest(...)` for a trusted event,
   or `.insights.read()` for permitted values. A raw keyring identifier is not
   needed. A new visit gets a new session, not a permanent identity token.

Insight writes require an approved company-activity dataset, registered fields
and a valid company session. Registered site observations are accepted unless the
holder stops collection. Reading shared values and audience matching have separate
owner controls. Marketing uses separate scoped
authentication; suggested engagement groupings are not a supplied SDK feature.

**Partner overhead:** one-time company/app configuration and backend secrets,
then the handler that supplies meaningful, permitted insight values. The supplied
wiring should handle connection, status, callback, expiry and logout. The current
SDK has the underlying helpers; the complete framework that joins them remains
to be delivered. The encrypted-cookie helper is available now, but it is not by
itself the complete callback workflow.

Start with [SDK setup](/developers/guides/sdk-setup.md), the
[window controller](/developers/guides/browser-window.md), and the
[company-insights example](/developers/downloads/mementom-company-insights.mjs).
The helper demonstrates server session and insight calls. The walkthrough adds a
Node route adapter with exact-origin POST checks, state-bound returns, status and
logout. It is a same-browser example, not an external-company QR relay. QR
completion must update the original requesting UX’s session status; merely
displaying or scanning a QR is not proof of completion.

## Tier 2: add rights and challenges

Retain Tier 1’s session. Configure an action and issue its rights invitation URL
or QR. When a person requests that action, your backend supplies the session,
action and resource, opens a service-issued challenge if required, verifies the
protected decision against the saved bindings, and consumes its one-use approval.
Only then run your business handler. Use an idempotent business operation to
avoid repeating it after a network failure.

**A rights invitation grants a right; it is not the connection exchange.** The
current standalone invitation flow does not return an application session to a
requesting page. Preserve the Tier 1 session, or complete the Tier 1 connection
before returning to the action. The desired combined QR journey must explicitly
join those steps; there is not yet a universal invitation-to-session adapter.

You supply what the action means, the resource being approved and the effect of
approval. Mementom supplies rights checks, challenge issuance, protected decisions
and one-use consumption. See the [API reference](/developers/api/) and
[backend contract](/developers/guides/backend-contract.md).

## Tier 3: add account sign-in

Retain Tiers 1 and 2. Enable account access for this app. On the first link, your
server verifies ownership of the customer account using your existing account
process, creates a private account reference and calls `linkAccountAccess()` for
the connected session. Never treat a browser-supplied account ID as ownership.

On later connections, `useAccountAccess()` checks and uses that account right.
Your server resolves the returned private reference to your own account and
creates your normal application login session. Recovery, account lifecycle and
permission to operate on that account remain your business rules. See the
[account linking guide](/developers/guides/vendor-account-access.md).

## Downloads and backend choices

- [Consolidated JavaScript server SDK](/developers/downloads/mementom-sdk.mjs):
  Node.js 22.12+, no third-party dependencies. Authentication, general company API,
  insights, optional session cookies and separately authenticated marketing.
- [Shared browser controller](/developers/downloads/mementom-browser.mjs):
  the same window lifecycle with every backend language.
- [Python HTTP reference](/developers/downloads/mementom_http.py): setup and
  insight HTTP examples, not a complete protected-decision implementation.
- [Language-neutral contract and coverage](/developers/guides/backend-contract.md):
  HTTPS/JSON and OpenAPI for Python, .NET, Java, PHP and Go.

Pin the downloaded source in your own repository. The private workspace package
`@mementom/sdk` is another distribution of the same JavaScript implementation;
there is no public package-registry installation to promise today. Older insight,
cookie and marketing download names are compatibility aliases to the consolidated
server module. Keep server code and secrets out of browser bundles.

## Where the framework work belongs

The repeated orchestration is the bulk of the burden we can remove. Available
helpers already handle configuration discovery, API calls, result verification,
session insight calls and the browser window lifecycle. Complete Express/React
adapters are still planned, not included in these downloads.

The framework target is a shared start/status/callback/cancel/logout workflow,
one-use attempt handling, expiry and failure handling, and UI refresh after
completion or closure. Developers should configure that workflow and supply:

- Application configuration and secrets. Session management and its storage belong
  to the supplied Mementom framework, not a partner storage implementation.
- Meaningful, permitted insight values and personalization handlers for Tier 1.
- Resource selection and approved-action handlers for Tier 2.
- Account verification, mapping and login hooks for Tier 3.

The workflow contract should remain backend-independent. Native adapters can
implement it without requiring a Node sidecar. Business policy and effects remain
explicit handlers rather than being inferred by the SDK.