Skip to main content

Best Practices

Recommendations for integrating the relay Embedded SDK reliably and securely. This page covers two critical topics: choosing the correct publishable key for each environment, and passing a stable user identity to the SDK.

Live vs Test Publishable Keys​

Every END_USER receives two publishable keys when they complete enrollment — a live key and a test key. Both are returned together in the onVerificationSuccess callback:

const sdk = Intellirent.init({
  publishableKey: "pk_live_xxx",
  userContext: { userId: "enduser_abc123", userType: "END_USER" },
});

await sdk.mount("#container", {
  view: "screening",
  onVerificationSuccess: async ({ liveKey, testKey }) => {
    // Store both keys securely on your backend.
    // Use testKey in development/QA, liveKey in production.
    await saveEndUserKeys({ liveKey, testKey });
  },
});

Store both. Use the test key during development and QA, and the live key in production.

Key prefixes​

The key prefix determines which Experian environment the SDK routes to — you cannot override this. Environment routing is fully derived from the key.

PrefixEnvironmentUse with
pk_live_ProductionReal consumer data
pk_test_TestExperian test consumer data (synthetic) only
caution

Test consumers (synthetic identities from Experian's test environment) will not work against a live key, and real consumers should never be screened with a test key. Mismatching the key and the consumer data will cause screenings to fail or return invalid results.

Choosing the right key​

Pass the appropriate key via an environment variable — never hardcode either key:

const sdk = Intellirent.init({
  publishableKey: process.env.RELAY_PUBLISHABLE_KEY,
  userContext: { userId: currentUser.id, userType: "END_USER" },
});

Authentication and userId​

The SDK does not manage authentication. Your platform is responsible for authenticating users and passing their identity to the SDK via userContext.userId on Intellirent.init().

const sdk = Intellirent.init({
  publishableKey: "pk_live_xxx",
  userContext: {
    userId: "a1b2c3d4-5e6f-7890-abcd-ef1234567890", // Cognito sub, Auth0 user_id, etc.
    userType: "CONSUMER",
  },
});

The userId you provide scopes access to screenings — it determines which screenings a user can see and access. The SDK trusts whatever value you pass it, so it is critical that this identifier is stable, unique, and comes from a trusted source.

What userId should be​

userId must be a stable, unique identifier from your own auth system. It must not change between sessions.

RecommendedAvoid
Cognito sub (UUID)Email address (can change)
Auth0 user_idDisplay name or username
Your own database primary key (UUID)Anything mutable or non-unique

Use your auth provider's immutable subject identifier whenever possible. Never derive userId from mutable profile fields such as email or display name.

Why stability matters​

If userId changes between sessions, the user loses access to the screenings tied to their previous identifier.

  • CONSUMER users: if userId changes (for example, because you switched from email to sub), the consumer will lose access to their in-progress screening.
  • END_USER users: userId must be consistent across all SDK calls in your system. Inconsistent IDs mean the end user may see an empty reports list or be unable to access screenings they own.
warning

Treat userId as a permanent foreign key into relay's screening data. Once a user has interacted with the SDK, their userId should never change. Migrating to a different identifier later will orphan their existing screenings.

Server-side validation​

The SDK trusts whatever userId you pass it. Always validate the user's session server-side before passing any identity to the SDK.

  • Verify the user's session token on your backend before rendering the SDK.
  • Resolve the user's immutable identifier from the validated session — not from client-side state, query strings, or local storage.
  • Pass that resolved identifier to the SDK on the client.
tip

Never accept userId directly from client-provided input. Always derive it from a server-validated session token (e.g., a verified Cognito JWT sub claim or Auth0 user_id).

Next Steps​