Guide · Identity

Phase two

Keep your login. Share only a stable customer identity.

Our Impact does not replace your authentication. Your server confirms who is signed in, then exchanges that trusted identity for a short-lived browser token.

The trust boundary

01

Your app authenticates

Use your existing session, SSO, magic link, or account system.

02

Your server identifies

Send the same stable external user ID every time that customer returns.

03

Our Impact authorizes

A 60–3600 second token permits browser reads for only that user and project.

Choose the external user ID

The external ID is the join between your customer record and their Our Impact activity.

  • Do: use an immutable internal database ID such as usr_01JABC.
  • Do: namespace IDs if several apps share a project, for example storefront:usr_01JABC.
  • Avoid: email addresses, display names, or anything a customer can change or claim.

Issue identity after authenticating your user

The identity route belongs in your application. It verifies your existing session and calls POST /api/v1/identity-tokens from the server.

1

Authenticate first, then create the token

app/api/our-impact/identity/route.ts
import { OurImpactClient } from "@our-impact/node";
import { auth } from "@/lib/auth";

const ourImpact = new OurImpactClient({
  secretApiKey: process.env.OUR_IMPACT_SECRET_KEY,
});

export async function POST() {
  const session = await auth();
  if (!session?.user?.id) {
    return Response.json({ error: "unauthorized" }, { status: 401 });
  }

  const identity = await ourImpact.identity.createIdentityToken({
    body: {
      externalUserId: "storefront:" + session.user.id,
      displayName: session.user.name ?? undefined,
      ttlSeconds: 900,
    },
  });

  return Response.json(identity);
}
2

Return only the short-lived result

200 OK
{
  "token": "oi_identity_opaque_value",
  "expires_at": "2026-11-11T08:15:00.000Z",
  "user": {
    "external_user_id": "storefront:usr_01JABC",
    "display_name": "Avery"
  }
}

Identify the embedded campaign

The browser SDK mounts the hosted campaign, supplies the same identity token, and follows content height without a nested scrollbar.

campaign-widget.ts
import { OurImpact } from "@our-impact/browser";

const impact = new OurImpact({
  publishableKey: "oi_pk_test_...",
  userToken: identity.token,
});

const campaign = impact.widgets.mountCampaign({
  target: "#our-impact-campaign",
  publicId: "your-campaign-id",
  height: "auto",
});

// When your signed-in customer changes:
impact.setIdentity(nextIdentityToken);

// During view cleanup:
campaign.destroy();

The widget still validates that the host origin appears in the project’s allowed-origin list. Use a numeric height only when you intentionally want a fixed, scrollable frame.

Handle sign-in, sign-out, and expiry

Tokens expire by design. Treat them like a short-lived projection of your application session, not a new login system.

our-impact-session.ts
async function signInToOurImpact() {
  const response = await fetch("/api/our-impact/identity", { method: "POST" });
  if (!response.ok) throw new Error("Could not identify supporter");

  const identity = await response.json();
  impact.setIdentity(identity.token);
}

function onSignedOut() {
  impact.clearIdentity();
}
  • Sign-in: request a token after your application knows the current user, then call setIdentity().
  • Sign-out or account switch: call clearIdentity() before showing another session.
  • Expiry: request a new token from your server and call setIdentity() again. Never persist the token as a durable account credential.

Production identity checklist

Identity endpoint requires your real application session.
External user IDs are immutable and at most 120 characters.
Secret key exists only in server-side environment variables.
Every browser origin is explicitly allowed in the developer project.
Account switches clear cached identity before loading the next user.
401 responses trigger token renewal, not secret-key exposure.