Skip to main content
POST
/
api
/
partner
/
handshake
{
  "success": true,
  "session_key": "<string>",
  "iframe_url": "<string>",
  "expires_in": 123
}

​
Endpoint

POST https://api.staging.usesticker.com/v1/partner/handshake

​
Authentication

​
Authorization
string
required
Bearer token with your Partner API Key
Bearer sk_test_your_api_key

​
Request Body

​
partner_org_id
string
required
Your internal identifier for the organization (must match the ID used in organization setup)
​
user
object
required
User information for authentication
​
user.email
string
required
User’s email address (must exist in organization)
​
user.first_name
string
required
User’s first name (auto-updates profile if changed)
​
user.last_name
string
required
User’s last name (auto-updates profile if changed)

​
Request Examples

{
  "partner_org_id": "acme_sf_001",
  "user": {
    "email": "dr.smith@acmemedical.com",
    "first_name": "John",
    "last_name": "Smith"
  }
}

​
Response

​
success
boolean
Whether the handshake succeeded
​
session_key
string
Secure, time-limited authentication token for the iframe
  • 64-character hex string
  • Single-use only
  • Expires in 5 minutes
​
iframe_url
string
Base URL for embedding StickerAppend ?session_key={session_key} to this URL
​
expires_in
number
Time in seconds until token expires (default: 300)

​
Response Examples

{
  "success": true,
  "session_key": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2",
  "iframe_url": "https://app.usesticker.com",
  "partner_org_id": "acme_sf_001",
  "expires_in": 300
}

​
Error Codes

CodeDescriptionSolution
INVALID_REQUESTMissing or invalid fieldsCheck required parameters
ORGANIZATION_NOT_FOUNDOrganization doesn’t existCall organization-setup first
USER_NOT_FOUNDUser not in organizationAdd user to organization
UNAUTHORIZEDInvalid API keyVerify API key
RATE_LIMIT_EXCEEDEDToo many requestsImplement backoff

​
Session Token Properties

Single-Use

Each token can only be used once

Time-Limited

Expires 5 minutes after creation

User-Specific

Tied to specific user and organization

Cryptographically Secure

64-character random hex string

​
Using the Session Token

Append the session token to the iframe URL: 
<iframe
  src="https://app.usesticker.com/${partnerOrgId}?session_key=a1b2c3d4..."
  width="100%"
  height="800px"
  frameborder="0"
  allow="payment"
  sandbox="allow-same-origin allow-scripts allow-forms allow-popups"
/>
Never reuse session tokens. Generate a fresh token for each user session, even if they just closed the supplies module.

​
Name Updates

The handshake endpoint automatically updates user names in Sticker: 
// User changed their name in your system
const updatedUser = {
  email: 'dr.smith@acmemedical.com',
  first_name: 'Jonathan', // Changed
  last_name: 'Smith'
};

// Next handshake will sync the name change
const result = await handshakeUser(orgId, updatedUser);
Email addresses cannot be changed via handshake—they’re the unique identifier. To change a user’s email, contact Sticker support.

​
Rate Limiting

The handshake endpoint is rate limited to:
  • 1,000 requests per hour per partner
  • 100 concurrent requests burst limit
This is generous for normal usage. Each handshake is typically called once per user session.

​
Best Practices

Create session tokens only when the user opens the supplies module, not in advance.
If a user takes > 5 minutes to load, generate a fresh token.
If handshake fails, show a clear error and retry button.
Log all handshake attempts for debugging and security auditing.

​
Testing

Test in the sandbox environment: 
POST https://api.staging.usesticker.com/v1/partner/handshake

{
  "partner_org_id": "test_org_123",
  "user": {
    "email": "test@example.com",
    "first_name": "Test",
    "last_name": "User"
  }
}
Sandbox tokens work the same as production tokens but connect to the sandbox application environment.