Partner Handshake - Sticker Partner Integration

Endpoint

POST /v1/partner/handshake

Base URL: https://api.usesticker.com Staging/Sandbox URL: https://staging.api.usesticker.com

Description

Creates an authentication session for a user to access the embedded Sticker iframe. Returns a secure, time-limited session token and the iframe embed URL. Workflow:

Partner authenticates with API key
Partner provides internal_user_id or profile_id to identify the user
Sticker finds the profile and validates it belongs to the partner
Sticker generates a temporary session token (5 minute expiry, single-use)
Returns session token + complete iframe embed URL

Authentication

Requires Partner API key in the X-API-Key header:

X-API-Key: sk_live_your_api_key_here

Request Body

You must provide either internal_user_id OR profile_id:

{
  "internal_user_id": "user-789"
}

{
  "profile_id": "660f9500-f30c-52e5-b827-557766551111"
}

Request Parameters

string

Your internal identifier for the user (provided during organization setup). Either this OR profile_id is required.

string

Sticker’s unique identifier for the user profile (UUID). Either this OR internal_user_id is required.

Using internal_user_id is recommended as it uses your system’s identifiers and doesn’t require storing Sticker profile IDs.

Response

Success Response (200 OK)

{
  "success": true,
  "session_key": "a1b2c3d4e5f6789012345678901234567890123456789012345678901234",
  "iframe_embed_url": "https://shop.usesticker.com/embedded/550e8400-e29b-41d4-a716-446655440000?session_key=a1b2c3d4e5f6789012345678901234567890123456789012345678901234",
  "expires_at": "2024-01-15T10:35:00.000Z",
  "profile": {
    "id": "660f9500-f30c-52e5-b827-557766551111",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@acmemedical.com"
  }
}

Response Fields

boolean

Whether the handshake succeeded.

string

Secure, time-limited token for authenticating the user in the iframe. 64-character hex string.

string

Complete URL to embed in an iframe. Includes the partner ID and session key already appended.

string

ISO 8601 timestamp when the session token expires. Tokens expire 5 minutes after generation.

object

Basic profile information for the authenticated user.

string

Sticker’s unique identifier for the profile (UUID).

string

User’s first name.

string

User’s last name.

string

User’s email address.

Error Responses

400 Invalid Request

{
  "error": "Invalid request body",
  "details": [
    {
      "code": "custom",
      "message": "Either internal_user_id or profile_id must be provided",
      "path": []
    }
  ]
}

Common causes:

Neither internal_user_id nor profile_id provided
Invalid UUID format for profile_id

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

Solution: Check your API key is correct and included in the X-API-Key header.

404 Profile Not Found

{
  "error": "Profile not found",
  "details": "No profile found with the provided credentials for this partner"
}

Solution: Ensure the user was created via the organization setup endpoint first. Verify the internal_user_id or profile_id is correct.

400 Profile Not Set Up

{
  "error": "Profile not set up for authentication",
  "details": "Profile must be linked to an auth user. Please complete setup first."
}

Solution: The profile exists but is not properly linked to an auth user. Contact Sticker support.

500 Session Creation Failed

{
  "error": "Failed to create authentication session",
  "details": "Database error message"
}

Solution: Retry with exponential backoff. Contact support if the error persists.

Session Token Properties

Session tokens have specific security properties:

Property	Description
Single-use	Invalidated immediately after first use
Time-limited	Expires 5 minutes after generation
User-bound	Tied to a specific user profile
Partner-bound	Can only be used with the partner’s iframe URL
Secure	64-character cryptographically random hex string

Never reuse session tokens. Generate a new token each time the user opens the supplies module, even if they just closed it seconds ago.

Code Examples

async function getHandshakeToken(userId) {
  const response = await fetch('https://api.usesticker.com/v1/partner/handshake', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.STICKER_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      internal_user_id: userId
    })
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Handshake failed: ${error.error}`);
  }

  return await response.json();
}

// Usage
const { session_key, iframe_embed_url } = await getHandshakeToken('user-789');
console.log('Embed URL:', iframe_embed_url);

import httpx
import os

async def get_handshake_token(user_id: str) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://api.usesticker.com/v1/partner/handshake",
            headers={
                "X-API-Key": os.getenv("STICKER_API_KEY"),
                "Content-Type": "application/json",
            },
            json={"internal_user_id": user_id}
        )
        
        response.raise_for_status()
        return response.json()

# Usage
result = await get_handshake_token("user-789")
print(f"Embed URL: {result['iframe_embed_url']}")

curl -X POST https://api.usesticker.com/v1/partner/handshake \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"internal_user_id": "user-789"}'

Using the Session Token

After receiving the handshake response, embed the iframe using the iframe_embed_url:

// React example
function SuppliesModule({ userId }) {
  const [iframeUrl, setIframeUrl] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function authenticate() {
      const response = await fetch('/api/supplies/auth', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ userId })
      });
      
      const { iframe_url } = await response.json();
      setIframeUrl(iframe_url);
      setLoading(false);
    }
    
    authenticate();
  }, [userId]);

  if (loading) return <div>Loading supplies...</div>;

  return (
    <iframe
      src={iframeUrl}
      className="w-full h-full border-0"
      title="Sticker Embedded Procurement"
      sandbox="allow-same-origin allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox allow-top-navigation-by-user-activation"
      allow="payment; publickey-credentials-get; fullscreen"
    />
  );
}

Best Practices

Generate on Demand

Create session tokens only when the user clicks to open the supplies module. Don’t pre-generate tokens.

Handle Expiration

If the iframe fails to load (e.g., user’s connection is slow), generate a fresh token and retry.

Never Cache

Don’t store or cache session tokens. They’re single-use and short-lived.

Server-Side Only

Always call the handshake endpoint from your backend. Never expose your API key in client-side code.

Error Recovery

If the handshake fails, show an error message and offer a retry button that generates a new token.

Organization Setup

Provision organizations and users before handshake

iframe Embedding

Best practices for embedding the Sticker iframe

​Endpoint

​Description

​Authentication

​Request Body

​Request Parameters

​Response

​Success Response (200 OK)

​Response Fields

​Error Responses

​Session Token Properties

​Code Examples

​Using the Session Token

​Best Practices

​Related

Organization Setup

iframe Embedding

Endpoint

Description

Authentication

Request Body

Request Parameters

Response

Success Response (200 OK)

Response Fields

Error Responses

Session Token Properties

Code Examples

Using the Session Token

Best Practices

Related