Skip to content

Install and set up the vendor SDK

Use the Rose vendor SDK to connect your product's server to Rose for Agents. It handles signed request verification and routing, and provides verification helpers for Handover. Your product keeps its existing account storage, permissions and business logic.

Contact your Rose account manager to arrange the integration and receive your SDK archive and server configuration.

1. Install

In your server project, using Node.js 22 or later and ES modules:

npm install ./userose-vendor-sdk-0.1.0.tgz

Use the archive supplied by Rose. The package includes JavaScript and TypeScript declarations; this release is distributed directly rather than through the npm registry.

Install the SDK on your server. Keep signing secrets in your server's secret manager.

2. Connect your product operations

Implement a VendorHandlers object using your existing product services:

Handler Connect it to
trial A limited product action that returns a useful sample result.
account Account creation or lookup for the verified buyer.
lookup For Handover, the buyer's existing account, including a claimed trial.
authorizeAccount A check that the account belongs to this buyer in this environment.
checkout Your offer activation and payment flow.
access The credentials and access your product grants.
use A permitted product action and its usage counter.

Then create the Rose request handler:

import {
  createVendorHandler,
  type SigningSecrets,
  type VendorHandlers,
} from '@userose/vendor-sdk';

export function connectProduct(
  origin: string,
  secrets: SigningSecrets,
  handlers: VendorHandlers,
) {
  return createVendorHandler({ origin, secrets, handlers, basePath: '/r4a' });
}

Set origin to your public API origin, such as https://api.example.com. Supply distinct test and production signing secrets from your secret manager. Rose coordinates the matching configuration with your team.

Mount the returned handler at /r4a/* in a server route that accepts a standard Web Request and returns a Response. Give Rose its base URL, such as https://api.example.com/r4a. If adapting another server framework, preserve the exact request body and public URL; avoid trusting arbitrary forwarded host headers.

Account lookup and permissions must use environment + buyerId as the owner. Do not merge users by email. Make account creation and payment operations safe to retry. The SDK calls authorizeAccount before checkout, access and use; recheck authorization in your product transaction if ownership or access can change concurrently.

For Handover, also implement lookup(buyer) to return {account_id} for an owned account or null if none exists. This supplies the signed GET /r4a/account endpoint so Rose can reuse an account before creating a trial. A missing lookup handler returns 503 and stops registration rather than creating a duplicate account.

For expected product errors, throw VendorError with an appropriate status, for example new VendorError(409, 'No active plan'). An unpaid checkout can throw new VendorError(402, {status: 'payment_required', amount_eur: 10}).

3. Connect Handover

For Handover, Rose provides a trust configuration with the issuer, vendor audience, client identifier, environment, accepted identity sources and public signing keys. Pass it to the verifier:

import { createHandoverVerifier } from '@userose/vendor-sdk';

const handover = createHandoverVerifier(roseTrustConfiguration);
const claim = await handover.verifyClaim(identityAssertion, {
  registrationId: trial.id,
  userCode: trial.userCode,
});
await yourDatabase.claimTrialAtomically(claim);

const event = await handover.verifyRevocation(signedEvent);
await yourDatabase.revokeBuyerAtomically(event);

Load trial from your database. The expected account and code must come from your stored trial, rather than unverified assertion fields or values supplied by a requester.

The SDK verifies proofs; your account transactions apply them. When claiming a trial:

  • Reject reused proofId values and check expiresAt at commit time.
  • Check the stored trial's code, expiry and owner, and resolve existing-account conflicts.
  • Preserve the account and usage, replace trial credentials and let the original assistant resume with the approved access.
  • Check that authenticatedAt is later than the buyer's stored revocation cutoff in the same transaction as the claim.

When revoking access, process eventId idempotently, advance the buyer's cutoff to at least issuedAt, and invalidate all delegated credentials and resume access before acknowledging the event. Older events must never lower the cutoff. Times use Unix seconds.

Trial creation, the claim page, credential delivery, resume and expiry are connected to your product as part of the integration. Rose will work through that setup with your team. Replace the verifier with the updated trusted key configuration when Rose rotates its signing keys.

4. Verify with Rose

Before rollout, test your configured integration together:

  1. A signed trial request reaches the intended product action; unsigned requests fail.
  2. Creating an account twice returns the same account for the same buyer and environment.
  3. Another buyer or environment cannot use that account.
  4. A claim keeps the existing trial account and usage, and replaces its credentials.
  5. Replayed claims fail, revocation stops access and an older authentication cannot restore it.

Return to Connect your product or the Rose for Agents overview.