Mementom Partner API

API Reference

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

See this API in the Aster demo

Version: v1
Base URL: https://mementom.app/api/v1
Format: application/json

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, email address, private image, or private phrase.

The person creates a private key ring from images and phrases 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, Mementom presents a private phrase. The person submits the matching key-ring image as proof of right. The company cannot see or access the window, phrase, image, or proof data.
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`

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
`vsub_`	Vendor-scoped anonymous subject	Connection code exchange
`chal_`	Challenge	Create challenge
`result_`	Decision result	Completed challenge

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-phrase 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.

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://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 and a durable vendor-scoped subject ID.

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": "...",
  "vendorSubjectId": "vsub_...",
  "identityAttributes": {},
  "resultId": "result_...",
  "expiresAt": "2026-08-24T19:12:00.000Z"
}

POST/connections/remove

Remove a connection

Terminates the vendor relationship for one vendorSubjectId 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://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
`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": "..."
}

POST/entitlements/grant

Grant an entitlement

Allows one vendor-scoped subject to use one challenge tag. 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/remove`	Remove a vendor relationship
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

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

Object IDs

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

Grant an entitlement

Remove an entitlement

Create a webhook endpoint

Body parameters

Delivery headers

List vendor events

List audit events

Endpoint index

`visibleDetails`