Mementom Partner API

API Reference

REST endpoints for connecting an anonymous customer relationship, requesting a protected action, and consuming a signed decision.

Build your first integration

Version: v1
Auth URL: https://auth.mementom.app/api/v1
Insights URL: https://mementom.app/api/v1
Format: application/json

Integrate Mementom into your company

Add a Connect button to your website. Let your backend save a useful observation from that visit. Confirm that it reached Mementom.

This walkthrough uses Node.js and Harbor Exchange as the worked example. You keep your own website, products and business logic. Mementom handles the person’s private key verification and the temporary connection.

Your first result: a visitor connects, returns to your site, and sees their connection status. Then your server can contribute a registered insight from a real action.

Start with your app

Already configured? Jump to sessions, QR display, behavioral insights or reading shared values.

1. Register your company’s app

Use an HTTPS development or staging site that your team already controls. This walkthrough calls it https://shop.example.com; replace that address with yours everywhere.

Register your company, or ask your company owner for developer access.
Open your app in the Developer Console. In Integration, enter your website and https://shop.example.com/mementom/return as the return address.
Leave account access off for this first connection. It does not sign a person into an existing customer account.
Download the generated mementom-setup.mjs from your app’s Integration page.

Check: the website and callback belong to your company. You are using your app’s ID, not Harbor’s.

2. Put the modules on your server

Use Node.js 22.12 or later. Download these files into one folder in your backend project, outside its public web directory. Keep their names unchanged.

The SDK makes the Mementom calls. The insight helper manages encrypted connection cookies. The route example connects those functions to your web server.

Add the generated setup file to the same folder. Review and commit these source files in your company repository to keep a known version.

Check: none of these server modules or secrets is included in your frontend bundle.

Your backend folder

your-company-server/
  mementom/
    mementom-sdk.mjs
    mementom-company-insights.mjs
    company-connection.mjs
    mementom-setup.mjs
  server.mjs

Using another backend language? Follow the HTTPS integration contract. This code walkthrough uses the JavaScript SDK.

3. Configure and run setup

Ask your company owner for the existing server credential. Keep it and the app’s matching RSA private key in your server’s secret manager. If this app has no key yet, follow the key-generation instructions.

Set the two values used by the generated setup file, then run node mementom-setup.mjs from its folder. Setup registers the public key and prepares the connection configuration. It does not send your private key.

In Insights → Catalog, register the field you want to contribute. Under Validation → Datasets, create a Company activity dataset containing that field. Copy its ID. Validate a value before sending a real observation.

For a Harbor-style shop, start with one meaningful shopping observation. Use its registered field key and allowed values exactly; do not assume Harbor’s dataset IDs belong to your app.

Check: setup succeeds, your connection challenge is published and selected, and your dataset contains approved fields.

APP_ORIGIN: Your HTTPS website origin, without a path.
MEMENTOM_APPLICATION_ID: The app ID in your generated setup.
MEMENTOM_DATASET_ID: Your Company activity dataset ID.
MEMENTOM_VENDOR_CREDENTIAL: Your company’s server credential. Secret.
MEMENTOM_RESPONSE_PRIVATE_KEY: The matching RSA private PEM key. Secret.
MEMENTOM_COOKIE_KEY: A random 32-byte key encoded as base64url. Secret; keep the same value across server instances and restarts.

Create a cookie key once

Run this in your server’s secure setup environment. Save the result in your secret manager; do not put it in Git or regenerate it on startup.

Cookie key command

node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))"

4. Mount the four routes

Initialize the downloaded route example once when your backend starts. Call its handle method before your normal page routes. It uses Node’s request and response objects; your existing HTTPS server or proxy stays in place.

POST /mementom/connect: Starts a connection and redirects to Mementom.
GET /mementom/return: Validates the return, exchanges the code, sets the encrypted session cookie and redirects to your home page.
GET /mementom/status: Returns connection status without exposing the session or insight values.
POST /mementom/disconnect: Ends the connection and clears its cookies.

Keep POST requests on your own origin. Preserve all Set-Cookie headers through your proxy. Exclude callback query strings from access logs.

Check: before connecting, your status route returns {"connected":false}.

Initialize in your backend

import { createCompanyConnection }
  from './mementom/company-connection.mjs';

const connection = await createCompanyConnection({
  appOrigin: process.env.APP_ORIGIN,
  applicationId: process.env.MEMENTOM_APPLICATION_ID,
  datasetId: process.env.MEMENTOM_DATASET_ID,
  credential: process.env.MEMENTOM_VENDOR_CREDENTIAL,
  privateKey: process.env.MEMENTOM_RESPONSE_PRIVATE_KEY,
  cookieKey: Buffer.from(
    process.env.MEMENTOM_COOKIE_KEY, 'base64url'),
  authorizationOrigin: 'https://auth.mementom.app',
  insightOrigin: 'https://mementom.app'
});

// First line inside your existing async request handler:
if (await connection.handle(request, response)) return;
// Your existing page and business routes continue here.

Use a matched pair of Mementom service origins for your environment. Never take these origins from a visitor’s request.

5. Add the button to your page

The first integration uses a normal redirect in the same tab. The person completes Mementom’s secure steps and returns to your home page. Your page then checks your own status route.

Place the form in your company’s page and load the status code from your frontend JavaScript. Only show a connected state after your backend confirms it.

Check: Connect → Mementom → your website. The address bar no longer contains code or state. Your page says Connected, and Disconnect returns it to Not connected.

Harbor adds a persistent QR badge and a separate authorization window. Add those after this flow works, using the shared browser controller and Harbor’s full integration guide.

In your HTML page

<form method="post" action="/mementom/connect">
  <button>Connect with Mementom</button>
</form>
<p id="connection-status" role="status">Checking connection…</p>
<form method="post" action="/mementom/disconnect" hidden
      id="disconnect-form">
  <button>Disconnect</button>
</form>

In your frontend JavaScript

const status = document.querySelector('#connection-status');
try {
  const response = await fetch('/mementom/status', {
    credentials: 'same-origin', cache: 'no-store'
  });
  if (!response.ok) throw new Error('Status unavailable');
  const { connected } = await response.json();
  status.textContent = connected ? 'Connected' : 'Not connected';
  document.querySelector('#disconnect-form').hidden = !connected;
} catch {
  status.textContent = 'Connection unavailable. Try again.';
}

6. Save one real observation

Call saveActivity from your existing server business handler after a real action. Your company chooses the observation; Mementom stores it against the current connection.

For Harbor, viewing a product or saving an item can update a shopping insight. An order placed is distinct from a payment confirmed. Do not trust a browser’s claim that it paid or earned a reward.

Construct values using your registered field keys and types.
Save the event ID, observation time and values with your business event before the first send.
Pass that same saved event to saveActivity(request, event). Keep its ID and contents unchanged when retrying.
Check the returned receipt. A successful write does not automatically allow your company to read or use the values for audience matching.

A valid company session permits registered site observations unless the owner has stopped collection. Reading values and audience matching have separate owner controls. An empty permitted-values response is valid.

Check: the receipt confirms accepted fields. The person can review the activity in Mementom. Sending the same event again produces a duplicate receipt rather than another contribution.

Inside your server business handler

// event is the record your business handler already saved:
// {
//   eventId: a stable unique ID for this observation,
//   observedAt: its original ISO timestamp,
//   values: registered field keys and observed values
// }
const receipt = await connection.saveActivity(request, event);
// Store the receipt with that event.
// Retry transport failures with this same event.
// Never change the timestamp to force an older value through.

The field named sample in the underlying API is the observation envelope. A normal ingest call writes a real observation; use console Validation for trial values.

See the exact insight request and response

Check your first integration

Guest browsing still works.
Connect returns to the correct visit and status becomes connected.
Cancel or an expired return never creates a new connection.
Refreshing the page preserves a valid connection.
One real action produces an accepted receipt; its retry is a duplicate.
Pausing collection is respected. Sharing controls remain separate.
Disconnect removes the connection.

Once these pass, add the capability your business needs next: protected actions, existing customer account sign-in, or offers and campaigns.

Try Harbor Exchange and compare the same steps. Its shopping, pricing and order handling belong to Harbor; your company supplies its own.

Task: connect behavior to the right session

Use the request from the browser that performed the action. The helper reads its encrypted HttpOnly cookie and selects the Mementom session on your server. Your frontend sends neither a session ID nor a keyring ID.

For example, after your server records a product view, pass that request and the saved observation to connection.saveActivity. A second visitor has a different cookie and session. A disconnected visitor cannot contribute through the old session.

Inside the supplied helper, these are the actual SDK calls. current(request) reads and checks the encrypted cookie; it is a helper function, not a browser value.

Check: use two browser profiles. Each visit must contribute only its own observations. Do not replay a guest’s earlier activity into a later connection.

How the helper assigns the session

const session = mementom.forSession(current(request));
const catalog = await mementom.insights.getCatalog();

const receipt = await session.insights.ingest({
  datasetId,
  expectedRevision: catalog.revision,
  eventId: event.eventId,
  sample: {
    schemaVersion: 1,
    observedAt: event.observedAt,
    values: event.values
  }
});

Read the complete helper source

Task: record views, saves and orders

Harbor turns its recorded shopping actions into registered insight values. These are real field keys from its source. Your app must register the corresponding definitions and dataset before using them.

The values are current totals for the connected visit, not increments. If the third product view takes the total to three, send 3. Send only the fields that changed.

Product view: Record that a known product was opened; update the server’s view count.
Save or unsave: Update the saved list first; contribute its resulting count.
Accepted order: Use the server’s persisted order, never browser-supplied price, payment or quantity claims.

The code uses savedObservation: your business event after your normal storage has saved its stable ID, original timestamp and trusted totals. It is not another Mementom API.

Check: refresh or idle polling produces no new write. The same saved event can be retried without changing its contents.

Three server-side business handlers

// Call the matching handler AFTER saving the business event.
async function productViewed(request, savedObservation) {
  return connection.saveActivity(request, {
    eventId: savedObservation.id,
    observedAt: savedObservation.observedAt,
    values: {
      'harbor.session.product_views': savedObservation.productViews
    }
  });
}

async function savedItemsChanged(request, savedObservation) {
  return connection.saveActivity(request, {
    eventId: savedObservation.id,
    observedAt: savedObservation.observedAt,
    values: {
      'harbor.session.saved_items': savedObservation.savedItems
    }
  });
}

async function orderAccepted(request, savedObservation) {
  return connection.saveActivity(request, {
    eventId: savedObservation.id,
    observedAt: savedObservation.observedAt,
    values: {
      'harbor.session.orders': savedObservation.orders,
      'harbor.session.units_ordered': savedObservation.unitsOrdered
    }
  });
}

An accepted order does not prove payment. A retry keeps the original observation totals; it does not rebuild them from the current cart.

Task: use permitted insights

Read on your backend using the same request’s connection. Only values currently shared with your application are returned. Use them to choose your own content or product order.

Do not interpret an empty list as a lost connection. It can mean the person has not shared values, or that previous values expired. Keep your ordinary experience available.

Check: changing the owner’s sharing choice changes the next read. Saving, sharing and audience matching stay separate.

Read from your backend

const { values } = await connection.readActivity(request);
// Choose your own content using only these permitted values.
// Do not send the session cookie, credential or private key to JS.
// An empty values array is a valid result.

Task: display the session QR

A QR code is an image of an issued link. For Harbor’s phone-to-desktop flow, that link comes from Mementom’s remote ceremony service. The relay returns completion to the browser visit that requested it.

This rendering function uses the same local QR encoder as Harbor. It makes no external image request. Give it the url and expiresAt from an issued relay response, plus your configured Mementom authorization origin.

Save the renderer and qr-code.js together in your browser assets. Put the encoder under their vendor/ folder and retain its license.

Session binding matters: Harbor’s relay endpoints are specific to its Mementom-hosted integration. The downloadable company route example above handles a same-browser return. It does not yet expose the company relay needed to connect an original desktop visit from a phone.

Use the next example to follow Harbor’s real flow. Encoding an ordinary connection URL as a QR does not supply that relay or transfer the original browser’s cookie.

QR markup

<div id="session-qr" aria-label="Mementom connection QR"></div>
<p id="qr-status" role="status"></p>

Render an issued session QR

import { showSessionQr } from './qr-display.js';

// issued comes from the Mementom relay, not a made-up URL.
const clearQr = showSessionQr({
  host: document.querySelector('#session-qr'),
  status: document.querySelector('#qr-status'),
  url: issued.url,
  expiresAt: issued.expiresAt,
  authorizationOrigin: 'https://auth.mementom.app'
});
// Call clearQr() when connected, cancelled, or leaving the page.

Check: an expired or replaced request disappears. Scanning alone never changes the page to Connected.

How Harbor finishes a QR connection

This is the working pattern inside Harbor, using its existing routes and shared components. It shows where session preparation, QR display, completion and refresh meet.

Harbor’s backend creates a signed connection request and binds it to the current visit.
The shared badge asks Mementom’s relay for the phone URL and renders its QR.
The phone finishes the service-issued ceremony. The relay supplies a verified continuation to the original browser.
The original browser calls Harbor’s return handler. The server checks the pending state and exchanges the one-use code.
Harbor refreshes its backend connection state, then enables connected shopping and insight contributions.

api, refreshConnection and the route names below belong to Harbor. An external company needs the corresponding registered relay and return integration; these are not additional SDK methods.

Check: the phone completes the ceremony while the original desktop visit becomes connected. Another open visit must stay unchanged.

Harbor browser source pattern

import { createPartnerSessionBadge }
  from '/shared/partner-session-badge.js';

const badge = createPartnerSessionBadge({
  host: document.querySelector('[data-connection]'),
  origin: location.origin,
  partner: 'harbor',
  prepareAuthorization: () => api('authorize', {
    challengeId: access.connectionChallengeId || 'connect'
  }),
  onConnect: startConnection,
  onDisconnect: () => disconnect(),
  onActivity: () => activityWindow.open(),
  onComplete: () => refreshConnection()
});
// After a verified backend status refresh:
badge.setConnected(connectionReady(), access.sessionReference);
// On route disposal:
// badge.dispose();

Read badge and relay source · Read Harbor browser source

Start here

What Mementom does

Mementom lets a person privately prove that they are the same person a company has seen before—or that they have the right to complete one exact action—without giving that company their name, an email tied to their identity, private image, or private caption.

The person creates a private key ring from images and captions they choose. A company can then ask Mementom one clear question at the moment it matters. Mementom checks the person privately and returns only the result the company needs.

The central idea

What is a challenge?

A challenge is one time-limited request from a company asking a person to prove that they have the right to do one exact thing.

That might mean signing in, entering a protected part of a site, taking a sensitive action, authorizing an action on the person’s behalf, receiving chosen personalization, or continuing a prior session or experience. A challenge can also require proof of the right to authorize a real-world event, such as allowing a technician into a home.

A challenge is not the person’s identity, an open-ended login, or permission to do anything else. It is bound to the action and context the company describes when it creates the challenge.

One challenge, from beginning to end

The company sets up

It registers its application and names the kinds of requests it will make with challenge tags.
The person connects

The company starts a connection. The person chooses Mementom, and the company keeps only the anonymous relationship Mementom returns.
The company asks

At the moment of need, it creates one challenge that says exactly what is being requested and what it applies to.
Mementom checks privately

Inside the secure Mementom window, the keyring supplies the required key image. The person enters its matching private caption. The requesting app receives only the scoped result, never the image, caption or credential proof.
The company gets one result

It retrieves the decision, confirms it matches the request, and uses it once before taking the action.

Plain-language glossary

The words used in this API

These names describe the pieces of the relationship. Select any linked term to jump to the API operation that creates or uses it.

CompanyThe organization using Mementom. The API may call it a vendor. ApplicationOne registered site, app, service, or device owned by that company. ConnectionThe private introduction between one person and one company. SessionThe anonymous relationship the company keeps after the person connects. Challenge tagA reusable name and explanation for a kind of proof request, such as proving the right to authorize home entry. ChallengeOne exact, time-limited request made for one person and one moment. DecisionMementom’s signed result saying whether the required proof was satisfied for that exact challenge. EntitlementAn optional permission or benefit a company records for the anonymous relationship.

Overview

Authentication

Partner requests use an HTTP Bearer credential issued when Mementom provisions a vendor. Send the credential only from backend services over HTTPS.

The credential has the form {vendorId}.{clientSecret}. Mementom authenticates it and derives the vendor scope. Do not repeat vendorId in request bodies unless an endpoint explicitly documents the field.

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer {vendorCredential}`
`Content-Type`	POST	`application/json`

Connect with three server settings

Save your website and return address in Integration, then download and run server setup. It includes your Application ID, registers the public key through the API, and prepares the selected challenges. Keep two secrets on your server: the company credential and private RSA response key.

The SDK retrieves the saved configuration, matches your private key locally, and loads decision-signing keys. It keeps settings in server memory for up to 60 seconds. Each attempt retains its original immutable settings; refreshes cannot change a pending attempt.

Origin, callbacks, company ID, challenge IDs and response-key IDs are not separate deployment settings. If you use the optional SDK cookie helper, keep its encryption key in your server’s secret store.

Download server SDK · Setup and migration guide

GET /applications/{applicationId}/integration-config is authenticated, vendor-scoped and read-only. POST /challenge-definitions/save uses the console’s validation and version checks for programmatic setup. The full contracts are in OpenAPI.

Node.js server

import { Mementom } from './mementom-sdk.mjs';
const sdk = await Mementom.connect({
  applicationId: process.env.MEMENTOM_APPLICATION_ID,
  credential: process.env.MEMENTOM_VENDOR_CREDENTIAL,
  privateKey: process.env.MEMENTOM_RESPONSE_PRIVATE_KEY,
});

const { client, configuration } = await sdk.forAttempt();
// Keep configuration with the pending server-side attempt.
const login = configuration.challenges.login;

Link an account to the current keyring

Use POST /access-rights/accounts/link after Mementom Login and your own account verification, bound to the same server-side attempt. Mementom derives the keyring from the current session.

Verify the person’s existing app account or complete your normal new-account onboarding.
Generate and store one opaque account reference on your server.
Call linkAccountAccess with the current personal Login session.
After sign-in, call useAccountAccess and open the mapped account only when allowed. No extra prompt or QR is needed.

The link persists across fresh Login sessions. Use listAccountAccess to discover permitted account references and checkAccountAccess to check current permission. New setup creates no account challenge. Existing integrations with a published protected-action policy retain its verified/consumed result. A denied check never creates a replacement account.

Invitations still grant new rights

Brands, vendors and partners can continue offering rights through authorization invitations. Account invitations remain private and single-claim; other rights retain their existing reusable QR/link options.

Account linking, invitations and recovery guide

Node.js server · verified account

// Use the configuration saved with this Login attempt.
// Your server already verified ownership of this app account.
const scope = {
  applicationId,
  sessionId,
  domain: configuration.origin,
  action: configuration.challenges.accountAccess.actionId,
};
const linked = await client.linkAccountAccess({
  ...scope,
  accountRef, // Generated once and stored with the app account.
  resourceLabel: 'Your workspace',
});
// Retry with the SAME reference after an uncertain response.
// Standard account access needs no second challenge.
// For an existing custom challenge policy, follow its verified decision flow.
if (linked.challengeRequired === false) {
  const { allowed } = await client.useAccountAccess({ ...scope, accountRef });
  // Open your mapped app account only when allowed is true.
}

Overview

Object IDs

IDs are opaque strings. Store them exactly as returned. Prefixes identify the object type; they do not grant access.

Prefix	Object	Created by
`vnd_`	Vendor	Vendor provisioning
`app_`	Application	Create application
`pol_`	Assurance policy	Create assurance policy
`rkey_`	Response key	Create response key
`ctag_`	Challenge tag	Create challenge tag
`sessionId`	Random, expiring app session	Connection code exchange; fresh for each new sign-in
`chal_`	Challenge	Create challenge
`result_`	Decision result	Completed challenge

Write and retrieve company insights

Your backend sends the current application session. Mementom resolves its keyring and returns only this app’s permitted values. Another company, or another app you own, has a separate record—even for the same field name.

1. Configure your application

Sign in to the Developer Console. Register your app, exact HTTPS callback and allowed site origins.
Use your existing company server credential, or have the owner create the first credential in company settings. It appears once. Replacing it invalidates the previous credential for all apps using it.
Publish the app’s Login connection challenge, select it in Integration → SDK setup, and register the server’s public RSA key. A draft or OFF challenge does not issue an authenticated session. Use your intended access policy; insight use does not require nCent’s membership policy or an unrelated action challenge.
In Insights → Catalog, register a standard field such as shopping.interest. Custom fields need owner/admin approval in Review.
In Validation → Datasets, register a non-sample Company activity dataset. Copy its ID and your application ID. Validate synthetic observations before sending live events.

2. Use the consolidated SDK

Use Node.js 22.12 or later. Save the server SDK and example together outside your public web directory. Add the browser controller to your browser assets. No npm package, repository access or Mementom database access is needed.

The server SDK includes authentication, insights and the optional session cookie helper. Review and commit the downloaded modules in your company repository to pin the exact source. Do not import a changing remote URL at runtime. Existing private-package users can use @mementom/sdk, @mementom/sdk/insights and @mementom/sdk/session-cookie.

3. Connect the current visit

The example exports createCompanyInsights. Await its initialization with the three SDK inputs: application ID, company credential and private RSA key. Also supply the dataset ID for your business data and your existing persistent 32-byte cookie encryption key. The same key must be available to every instance of your backend.

On a direct tap, open a named authorization popup pointing to your backend’s sign-in route. Require a same-origin request. If blocked, offer a retry; do not collect credentials on your page.
Call beginSignIn(), set its setCookie response header and send a 303 to its location. The prepared URL preserves Mementom’s issued request and required popup marker.
At your registered callback, call finishSignIn(request, {code, state}) with the URL parameters. Append both returned cookies as separate Set-Cookie headers, then redirect to your own clean completion page. Never log the callback query.
The completion page may close the popup; the original site refreshes its own status. Keep session IDs and company credentials out of browser JavaScript. For QR, cancel/status and advanced destination flows, reuse the established authorization integration.

4. Respect collection and sharing choices

A valid company session permits registered company observations unless the owner has stopped collection. Saving a value does not enable company reads or audience matching. Those have separate owner controls in Mementom.

Honor the current dataset, destination scope and owner settings. Company reads return only permitted values; an empty result is valid. Your company cannot auto-enable sharing or audience matching.

5. Write and read

Call saveActivity(request, event) with meaningful insight values, such as an expressed preference or confirmed purchase, then readActivity(request). Persist the event ID, original observation time and values before sending. Reuse them for bounded retries. A browser-submitted claim is not evidence of a purchase or other business event.

The cookie carries only a temporary encrypted session; you do not need a consumer/keyring database. On a later sign-in, Mementom resolves the fresh session to the same permitted, unexpired records. Never use a saved session as permanent identity.

Use signOut(request, registeredReturnUrl) for logout, with your fixed company return URL and CSRF protection. Apply both cookie-clearing headers and send a 303 to the returned location so Mementom also clears this app’s browser-held file access. If no session cookie exists, location is absent; return to your own signed-out page. The server session is invalidated before this redirect.

Acceptance checklist

Verify write/readback, a later session, no permission, withdrawal, changed domains, expired sessions and duplicate events. Write different values for the same field in two company apps and confirm each retrieves only its own. No bounty or cross-company disclosure is enabled by this integration.

Backend setup

import {createCompanyInsights}
  from './vendor/mementom-company-insights.mjs';

const mementom = await createCompanyInsights({
  applicationId: process.env.MEMENTOM_APPLICATION_ID,
  datasetId: process.env.MEMENTOM_DATASET_ID,
  credential: process.env.MEMENTOM_VENDOR_CREDENTIAL,
  privateKey: process.env.MEMENTOM_RESPONSE_PRIVATE_KEY,
  cookieKey: Buffer.from(
    process.env.MEMENTOM_COOKIE_KEY, 'base64url'),
  authorizationOrigin: 'https://auth.mementom.app',
  insightOrigin: 'https://mementom.app'
});

// event is a persisted, server-observed event.
await mementom.saveActivity(request, event);
const {values} = await mementom.readActivity(request);

Two origins: sign-in and code exchange use auth.mementom.app. Insight calls use mementom.app. Both run on your backend.

No personal credentials: images, captions, files and management proof remain exclusively inside Mementom’s authorization surface.

Read behavior: only latest permitted unexpired values are returned. An empty array is valid; it can mean no data or no sharing permission. It is not proof of consent.

Insight HTTP contract

POST JSON to https://mementom.app/api/v1/insight-integration/ with Authorization: Bearer <company credential>. Calls carrying browser Origin or Sec-Fetch-Site headers are rejected. Never proxy a browser-selected ring, app or arbitrary insight payload.

catalog: Send {applicationId}. Returns definitions, datasets and the current revision.
validate: Send applicationId, expectedRevision, datasetId and 1–50 samples. Returns per-row results; writes no consumer data. Validation advances the workspace revision, so reload the catalog before ingesting.
ingest: Send applicationId, sessionId, expectedRevision, datasetId, eventId and sample. The sample is a live observation envelope—not a dry run. Returns a receipt with accepted count and duplicate flag.
read: Send {applicationId, sessionId}. Returns schemaVersion and values containing key, version, value, observedAt, expiresAt and provenance. No persistent holder ID is returned.

eventId is 8–80 letters, digits, underscores or hyphens. Values must match the dataset’s approved enum, boolean or bounded-integer definitions. Observation times include a timezone, cannot be future-dated, and must remain within each field’s TTL.

Deduplication retains the last 500 events per application/keyring. Do not replay older business events indefinitely. The dataset’s legacy status label is not permission: ingestion requires a non-sample company-asserted dataset, approved fields, current session and holder consent.

Failure handling

401: check your credential; insight_session_required means sign in again. Do not replace the session with a remembered identity.
403: insight_permission_required means ask the holder to review the dataset. company_server_required means move the call to your backend.
409: refresh the catalog and inspect the error. A reused event with different data or an older conflicting value must not be forced through by changing its time.
400/404: correct the schema or registered application. Do not retry unchanged input.
Network failure: retry with bounded backoff and the identical persisted event. Log status, error code and activityId, not credentials, session IDs or insight values.

Full request and response schemas are in OpenAPI 3.1. Collection withdrawal stops writes, reads and matching. An individual “Don’t share” choice blocks retrieval of that value; it does not turn off separately enabled collection.

Live observation envelope

{
  "schemaVersion": 1,
  "observedAt": "2026-09-29T12:00:00Z",
  "values": {"shopping.interest": "compared"}
}

Use your real event time and registered values. This illustration will expire and must not be copied as a current observation.

Overview

Errors

The API uses standard HTTP response status codes and returns a stable machine-readable error value. A human-readable message may also be present.

Status	Meaning
`400`	Invalid request or unavailable ceremony state
`401`	Missing or invalid vendor credential
`404`	Resource is unavailable in the authenticated vendor scope
`409`	Version, idempotency, lifecycle, or consumption conflict
`500`	Unexpected service error

Idempotency

gateRequestId is the idempotency key for creating a challenge. Replaying an identical request returns the same challenge. Reusing the ID with changed bindings returns 409 gate_request_conflict.

POST/applications

Create an application

Registers one web, native, service, or device application under the authenticated vendor.

Body parameters

Parameter	Type	Required
`displayName`	string	Yes
`applicationType`	enum	Yes
`redirectUris`	string[]	Yes
`allowedOrigins`	string[]	Yes
`branding`	object	No

Node.js SDK

const application = await mementom.createApplication({
  displayName: "Repair Visits",
  applicationType: "web",
  redirectUris: ["https://partner.example/mementom/return"],
  allowedOrigins: ["https://partner.example"]
});

201 response

{
  "applicationId": "app_...",
  "vendorId": "vnd_...",
  "displayName": "Repair Visits",
  "applicationType": "web",
  "status": "active"
}

POST/assurance-policies

Create an assurance policy

Defines the minimum number of complete memkey proofs required for a relationship and the number of complete-key proofs required for recovery. Two distinct image-and-caption pairs remain two memkeys even when they use the same image.

Body parameters

Parameter	Type	Required
`name`	string	Yes
`minimumMemkeys`	integer	Yes
`recoveryProofs`	integer	No

Node.js SDK

const policy = await mementom.createAssurancePolicy({
  name: "Protected action",
  minimumMemkeys: 2,
  recoveryProofs: 2
});

201 response

{
  "policyId": "pol_...",
  "minimumMemkeys": 2,
  "recoveryProofs": 2,
  "status": "active",
  "version": 1
}

POST/response-keys

Create a response key

Registers the RSA public JWK Mementom uses to encrypt decisions. Keep the corresponding private key in the partner backend.

Body parameters

Parameter	Type	Required
`applicationId`	string	No
`publicJwk`	RSA JWK	Yes

Node.js SDK

const responseKey = await mementom.createResponseKey({
  applicationId: "app_...",
  publicJwk
});

201 response

{
  "responseKeyId": "rkey_...",
  "algorithm": "RSA-OAEP-256+A256GCM",
  "status": "active",
  "version": 1
}

POST/challenge-tags

Create a challenge tag

Creates a reusable protected-action type. Runtime challenge requests use the returned challengeTagId, not the human-readable key.

Body parameters

Parameter	Type	Required
`key`	string	Yes
`displayName`	string	Yes
`description`	string	Yes
`coverageCount`	integer	No
`minimumMemkeys`	integer	No
`retryLimit`	integer	No
`distinctFromAccess`	boolean	No
`responseKeyId`	string	Yes
`networkPolicyId`	string	No

Node.js SDK

const tag = await mementom.createChallengeTag({
  key: "home-entry.scheduled-repair",
  displayName: "Scheduled home entry",
  description: "Require proof of right for one scheduled repair visit.",
  coverageCount: 1,
  minimumMemkeys: 2,
  responseKeyId: "rkey_..."
});

201 response

{
  "challengeTagId": "ctag_...",
  "key": "home-entry.scheduled-repair",
  "status": "active",
  "version": 1
}

GET/challenge-tags

List challenge tags

Returns every challenge tag owned by the authenticated vendor.

POST/connection-requests

Create a connection request

Starts a one-use Mementom connection ceremony. Persist the cryptographic state before opening the returned consumerUrl.

For a Login challenge published in the console, send {applicationId: configuration.applicationId, challengeActionId: configuration.challenges.login.actionId, state} from an SDK attempt snapshot (include its responseDestinationId when present). Policy, registered callback and displayed context come from that saved challenge. The policy and visible-context fields below apply to the separate explicit-configuration mode; do not add them to the managed Login request.

If establishing the relationship is also the first exact protected action, include authorization. The person then provides one Mementom proof; exchanging the returned code creates the anonymous session and returns a resultId for that same action. Omit it when connection and authorization are separate moments.

Body parameters

Parameter	Type	Required
`applicationId`	string	Yes
`policyId`	string	Yes
`returnUri`	URI	Yes
`visiblePurpose`	string	Yes
`requestedRights`	string[]	Yes
`visibleConsequence`	string	Yes
`state`	string	Yes
`opaqueCustomerReference`	string	No
`authorization`	object	No

Node.js SDK

const state = crypto.randomBytes(32).toString("base64url");
await pendingConnections.insert({ state, customerId });

const request = await mementom.createConnectionRequest({
  applicationId: "app_...",
  policyId: "pol_...",
  returnUri: "https://partner.example/mementom/connected",
  visiblePurpose: "Use Mementom for protected actions.",
  requestedRights: ["Prove the right to perform protected actions"],
  visibleConsequence: "The displayed action can proceed after successful proof.",
  authorization: {
    challengeTagId: "ctag_...",
    gateRequestId: "gate_...",
    action: "authorize-home-entry",
    resourceDigest: "sha256:...",
    visibleDetails: {
      actionLabel: "Authorize home entry",
      resourceSummary: "Repair visit at 18 Cedar Lane",
      consequence: "Allow the scheduled technician to enter for this repair.",
      expiresAt: "2026-08-24T18:42:00.000Z"
    }
  },
  state
});

201 response

{
  "requestId": "creq_...",
  "connectionRequestToken": "...",
  "consumerUrl": "https://auth.mementom.app/?connect=...",
  "expiresAt": "2026-08-24T18:42:00.000Z"
}

POST/connections/session

Exchange a connection code

After validating the callback state, exchange the one-use code for a short-lived Mementom session without a persistent key-ring identifier.

Also verify that the returned requestId equals the request saved when sign-in began. The downloadable integration example binds both state and request ID in an encrypted, expiring browser cookie.

When the connection request carried an authorization object, this response also includes resultId. Retrieve, verify, and consume it through the normal decision flow; do not create a second challenge for the same action.

Body parameters

Parameter	Type	Required
`applicationId`	string	Yes
`code`	string	Yes

Node.js SDK

const session =
  await mementom.exchangeConnectionCode(
    "app_...",
    callback.code
  );

200 response

{
  "tokenType": "MementomSession",
  "sessionId": "...",
  "identityAttributes": {},
  "resultId": "result_...",
  "expiresAt": "2026-08-24T19:12:00.000Z"
}

POST/connections/remove

Remove a connection

Resolves the current applicationId and sessionId inside Mementom, then terminates that company connection and invalidates its active sessions, challenges, decisions, and entitlements.

POST/challenges

Create a challenge

Creates one protected action bound to an application, session, anonymous subject, challenge type, application state, and exact resource digest.

Body parameters

Parameter	Type	Required
`applicationId`	string	Yes
`sessionId`	string	Yes
`challengeTagId`	string	Yes
`gateRequestId`	string	Yes
`state`	string	Yes
`action`	string	Yes
`resourceDigest`	SHA-256 digest	Yes
`visibleDetails`	object	Yes
`returnUri`	URI	Yes

`visibleDetails`

Property	Type	Required
`actionLabel`	string	No
`resourceSummary`	string	Yes
`consequence`	string	Yes
`expiresAt`	ISO 8601	No

Node.js SDK

const gate = await mementom.createChallenge({
  applicationId: "app_...",
  sessionId,
  challengeTagId: "ctag_...",
  gateRequestId: crypto.randomUUID(),
  state: crypto.randomBytes(32).toString("base64url"),
  action: "authorize-home-entry",
  resourceDigest: sha256(canonicalResource),
  visibleDetails: {
    actionLabel: "Authorize home entry",
    resourceSummary: "Repair visit · Aug 28 · 10 AM",
    consequence: "The assigned technician may enter for this visit."
  },
  returnUri: "https://partner.example/mementom/result"
});

201 response

{
  "challengeId": "chal_...",
  "gateRequestId": "...",
  "challengeUrl": "https://auth.mementom.app/?challenge=...",
  "expiresAt": "2026-08-24T18:52:00.000Z",
  "idempotentReplay": false
}

202 returns setupUrl when additional Mementom setup is required.

200 returns the existing URL for an identical idempotent replay.

409 returns gate_request_conflict if the ID is reused with changed bindings.

POST/decisions/retrieve

Retrieve a decision

Returns the encrypted decision envelope associated with the opaque result ID. The result must belong to the authenticated vendor and must not be expired.

Body parameters

Parameter	Type	Required
`resultId`	string	Yes

Node.js SDK

const retrieved =
  await mementom.retrieveDecision(resultId);

200 response

{
  "resultId": "result_...",
  "decisionEnvelope": { "...": "encrypted JWE" },
  "status": "issued",
  "expiresAt": "2026-08-24T18:57:00.000Z"
}

POST/decisions/consume

Consume a decision

Atomically consumes a verified decision. The SDK normally performs retrieval, decryption, signature verification, binding verification, and consumption through handleResult.

Body parameters

Parameter	Type	Required
`applicationId`	string	Yes
`sessionId`	string	Yes — current session
`resultId`	string	Yes
`nonce`	string	Yes

Recommended SDK flow

const result = await mementom.handleResult(
  resultId,
  expectedBindings
);

if (result.outcome === "allow") {
  await performBoundBusinessAction();
}

200 response

{
  "consumed": true,
  "resultId": "result_...",
  "receipt": "..."
}

Issue authorization links and QR codes

Your backend can issue an authorization when your own rules confirm an achievement or unlock a challenge. Return its invitationUrl or qrSvg to your page. Keep the company credential on your server.

Optional capabilityPolicy applies the same read/write capabilities and offer filters shown in Permissions and Shared key settings. Use offers.items for viewing and responding, and offers.definitions for authoring. Vendor IDs, any selected tag and a strict price ceiling narrow access together. Blank filters add no restriction. See KeyCapabilityPolicy in the API contract.

Use claimLimit: 1 for one keyring holder. Use claimLimit: null for unlimited keyring holders, such as a public company-access QR. Omit claimMinutes for no claim deadline with either option. Creating or viewing an invitation does not grant access; the holder must accept it.

Time limits and maximumUses apply separately to each granted right. Repeated claims preserve the existing right, including spent uses and revocation. A reusable QR is public access; anyone who proves control of a keyring can accept.

Claiming adds permission; it does not sign the holder into your application. Use the existing connection ceremony if your backend needs a verified company relationship.

Manage invitations and rights with POST /access-rights/list and POST /access-rights/manage. Check current permission with POST /access-rights/check. Canceling a reusable QR stops future claims; edit or revoke granted rights separately.

Server SDK

// Your company backend, after its eligibility check:
const invitation = await client.createAuthorizationInvitation({
  applicationId,
  challengeActionId: 'private-auction',
  claimLimit: 1,
  maximumUses: 1,
  claimMinutes: 60
});
// Display invitation.invitationUrl or invitation.qrSvg.

// Create once, then reuse on your company's pages:
const publicAccess = await client.createAuthorizationInvitation({
  applicationId,
  challengeActionId: 'login',
  claimLimit: null
});

POST/entitlements/grant

Grant an entitlement

Uses the current app session to assign one challenge tag. Mementom resolves the key ring privately. expiresAt is optional.

POST/entitlements/remove

Remove an entitlement

Removes access to one challenge tag and invalidates stale decisions for that entitlement.

POST/webhooks

Create a webhook endpoint

Registers an HTTPS receiver. The HMAC-SHA256 signing secret is returned once. Verify the raw request body with the timestamp and signature headers before processing an event.

Body parameters

Parameter	Type	Required
`endpointUrl`	HTTPS URI	Yes

Delivery headers

Header	Value
`mementom-event-id`	Unique event ID
`mementom-timestamp`	Unix timestamp
`mementom-signature`	`v1={base64url HMAC}`

const webhook = await mementom.post("/api/v1/webhooks", {
  endpointUrl: "https://partner.example/mementom/webhook"
});

Verify

const event = verifyWebhookEvent(
  rawRequestBody,
  request.headers,
  webhookSigningSecret
);

GET/events

List vendor events

Returns up to 100 recent events for the authenticated vendor, including decision.available and connection lifecycle events.

GET/audit

List audit events

Returns sanitized audit events for the authenticated vendor. Pass connectionId as an optional query parameter to filter the result.

All operations

Endpoint index

Method	Path	Purpose
POST	`/applications`	Create an application
POST	`/assurance-policies`	Create an assurance policy
POST	`/assurance-policies/update`	Update policy with optimistic versioning
POST	`/response-keys`	Create a decision response key
POST	`/response-keys/rotate`	Rotate or compromise a response key
POST	`/network-policies`	Create a network policy
POST	`/challenge-tags`	Create a challenge tag
GET	`/challenge-tags`	List challenge tags
POST	`/challenge-tags/update`	Update challenge-tag configuration
POST	`/challenge-tags/lifecycle`	Suspend, activate, or retire a tag
POST	`/connection-requests`	Create a connection ceremony
POST	`/connections/session`	Exchange a one-use connection code
POST	`/connections/logout`	End a session; follow the returned authorization-surface cleanup URL
POST	`/insight-integration/catalog`	Read this app’s registered fields and datasets (insights origin)
POST	`/insight-integration/validate`	Validate synthetic samples without writing holder data (insights origin)
POST	`/insight-integration/ingest`	Save a permitted observation through the current session (insights origin)
POST	`/insight-integration/read`	Retrieve this app’s permitted current values (insights origin)
POST	`/connections/remove`	Remove a vendor relationship
POST	`/access-rights/accounts/link`	Link a verified app account using the current personal session
POST	`/access-rights/accounts`	Discover accounts permitted for the current app session
POST	`/access-rights/check`	Check current permission for an exact account or right
POST	`/authorization-invitations`	Invite a keyring holder to accept new rights
POST	`/entitlements/grant`	Grant access to a challenge tag
POST	`/entitlements/remove`	Remove access to a challenge tag
POST	`/challenges`	Create a protected action
POST	`/decisions/retrieve`	Retrieve an encrypted decision
POST	`/decisions/consume`	Atomically consume a decision
POST	`/forced-challenge-campaigns`	Create a forced-challenge campaign
POST	`/forced-challenge-campaigns/activate`	Activate a scheduled campaign
POST	`/webhooks`	Register a webhook endpoint
GET	`/events`	List vendor events
GET	`/audit`	List sanitized audit events

API Reference

Integrate Mementom into your company

1. Register your company’s app

2. Put the modules on your server

3. Configure and run setup

4. Mount the four routes

5. Add the button to your page

6. Save one real observation

Check your first integration

Task: connect behavior to the right session

Task: record views, saves and orders

Task: use permitted insights

Task: display the session QR

How Harbor finishes a QR connection

What Mementom does

What is a challenge?

One challenge, from beginning to end

The company sets up

The person connects

The company asks

Mementom checks privately

The company gets one result

The words used in this API

Authentication

Headers

Connect with three server settings

Link an account to the current keyring

Invitations still grant new rights

Object IDs

Write and retrieve company insights

1. Configure your application

2. Use the consolidated SDK

3. Connect the current visit

4. Respect collection and sharing choices

5. Write and read

Acceptance checklist

Insight HTTP contract

Failure handling

Errors

Idempotency

Create an application

Body parameters

Create an assurance policy

Body parameters

Create a response key

Body parameters

Create a challenge tag

Body parameters

List challenge tags

Create a connection request

Body parameters

Exchange a connection code

Body parameters

Remove a connection

Create a challenge

Body parameters

visibleDetails

Retrieve a decision

Body parameters

Consume a decision

Body parameters

Issue authorization links and QR codes

Grant an entitlement

Remove an entitlement

Create a webhook endpoint

Body parameters

Delivery headers

List vendor events

List audit events

Endpoint index

`visibleDetails`