Integration Overview

Architecture Overview

Sticker’s embedded integration follows a simple but secure architecture that keeps your users authenticated across both platforms while providing a seamless procurement experience.

Integration Components

Backend Integration

Two API endpoints to call from your backend server

Frontend Embedding

iframe component to display Sticker in your UI

Organization Management

Automatic provisioning of orgs, users, and billing

Session Authentication

Secure, time-limited tokens for each user session

Two API Endpoints, That’s It

The entire integration requires just two API calls:

1. Organization Setup (One-Time)

Called when a customer enables procurement in your platform.

POST /v1/organizations/setup

Creates:

Organization with Stripe customer for billing
User profile linked to Supabase Auth
Shipping locations for order delivery

2. Partner Handshake (Per-Session)

Called every time a user opens the supplies module.

POST /v1/partner/handshake

Returns:

Session token (5 min, single-use)
Complete iframe embed URL

Integration Flow

One-Time Setup Flow

This happens once when a customer enables procurement:

Customer Enables Supplies

A customer clicks “Enable Supplies” in your platform

Gather Data

Collect organization name, user info, and shipping addresses from your system

Call Organization Setup

Send data to Sticker:

POST /v1/organizations/setup
{
  "internalOrgId": "your-org-id",
  "organizationName": "Customer Org",
  "internalUserId": "your-user-id",
  "user": {
    "firstName": "...",
    "lastName": "...",
    "email": "..."
  },
  "shippingLocations": [...]
}

Store Response

Optionally store the returned profile.id for reference

Enable UI

Show the supplies module in your navigation

Per-Session Authentication Flow

This happens every time a user opens supplies:

User Clicks Supplies

User navigates to the supplies section

Call Handshake

From your backend, call Sticker:

POST /v1/partner/handshake
{
  "internal_user_id": "your-user-id"
}

Get iframe URL

Response contains complete embed URL:

{
  "iframe_embed_url": "https://shop.usesticker.com/embedded/{partner}?session_key={token}"
}

Embed iframe

Display the iframe in your UI

User Shops

User browses, orders—all within your platform

Data Models

Sticker maps users into organizations using a many-to-one structure:

An organization is the customer business, company, practice, store, school, or legal entity.
A profile is an employee or user inside that organization.
One organization can have many profiles.
Each distinct customer business must have a unique internalOrgId.

Do not reuse a single internalOrgId for multiple unrelated businesses. Sticker treats that value as the business identity. Reusing it will group all of those users into one Sticker organization.

What You Send

// Organization Setup Request
{
  internalOrgId: string;        // YOUR unique business/org ID
  organizationName: string;     // Display name
  
  internalUserId: string;       // YOUR user/employee ID
  user: {
    firstName: string;
    lastName: string;
    email: string;
    phoneNumber?: string;
  };
  
  shippingLocations?: [{
    internalShippingLocationId: string;
    name: string;
    address: {
      line1: string;
      city: string;
      province: string;
      postalCode: string;
    };
    isDefault?: boolean;
  }];
}

What You Receive

// Organization Setup Response
{
  success: true,
  data: {
    organization: {
      id: string;             // Sticker org UUID
      stripeCustomerId: string;
    },
    profile: {
      id: string;             // Sticker profile UUID
      internal_user_id: string;  // Your ID echoed back
    },
    shippingLocations: [...],
    isNewOrganization: boolean;
  }
}

// Handshake Response
{
  success: true,
  session_key: string;
  iframe_embed_url: string;    // Use this directly!
  expires_at: string;
  profile: {
    id: string;
    first_name: string;
    last_name: string;
    email: string;
  }
}

Security Model

API Key Authentication

All API requests require your Partner API Key. Never expose it in client-side code.

// Organization Setup
Authorization: Bearer sk_live_xxx

// Handshake
X-API-Key: sk_live_xxx

Session Tokens

5 minute expiry - Must be used quickly
Single-use - Invalidated after first use
User-bound - Tied to specific profile
Partner-bound - Only works with your iframe URL

iframe Sandboxing

The iframe runs with restricted permissions:

sandbox="allow-same-origin allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox allow-top-navigation-by-user-activation"

What’s Included Out of the Box

When you embed Sticker, your users get:

Feature	Description
Product Catalog	10,000+ products across categories
Smart Search	Algolia-powered instant search
Shopping Cart	Multi-item cart with quantity management
Multiple Locations	Select from org’s shipping addresses
Payment Methods	Org-level saved payment methods
Coupon Support	Partner-funded discounts
Order History	View past orders and status
Favorites	Save frequently ordered items

Environments

Environment	API Base URL	Keys
Production	`https://api.usesticker.com/v1`	`sk_live_*`
Staging/Sandbox	`https://api.staging.usesticker.com/v1`	`sk_test_*`

Use sandbox for development and testing. Sandbox data is isolated from production.

Rate Limits

Endpoint	Rate Limit
Organization Setup	100/minute
Handshake	300/minute

Implement exponential backoff for 429 responses.

Next Steps

Organization Setup

Provision organizations and users

User Handshake

Authenticate users for each session

iframe Embedding

Display Sticker in your application

Best Practices

Tips for a robust integration

Get Started

Integration Guide

Advanced

Architecture Overview

Integration Components

Backend Integration

Frontend Embedding

Organization Management

Session Authentication

Two API Endpoints, That’s It

1. Organization Setup (One-Time)

2. Partner Handshake (Per-Session)

Integration Flow

One-Time Setup Flow

Per-Session Authentication Flow

Data Models

What You Send

What You Receive

Security Model

What’s Included Out of the Box

Environments

Rate Limits

Next Steps

Organization Setup

User Handshake

iframe Embedding

Best Practices

​Architecture Overview

​Integration Components

Backend Integration

Frontend Embedding

Organization Management

Session Authentication

​Two API Endpoints, That’s It

​1. Organization Setup (One-Time)

​2. Partner Handshake (Per-Session)

​Integration Flow

​One-Time Setup Flow

​Per-Session Authentication Flow

​Data Models

​What You Send

​What You Receive

​Security Model

​What’s Included Out of the Box

​Environments

​Rate Limits

​Next Steps

Organization Setup

User Handshake

iframe Embedding

Best Practices

Architecture Overview

Integration Components

Two API Endpoints, That’s It

1. Organization Setup (One-Time)

2. Partner Handshake (Per-Session)

Integration Flow

One-Time Setup Flow

Per-Session Authentication Flow

Data Models

What You Send

What You Receive

Security Model

What’s Included Out of the Box

Environments

Rate Limits

Next Steps