API Authentication

Overview

The Sticker Partner API uses API key authentication. Your API key identifies your partner account and authorizes access to your organizations and users.

Getting API Credentials

Contact the Sticker team to receive:

Partner ID (UUID) - Your unique partner identifier
API Key (string) - Starts with sk_live_ or sk_test_

# Store these as environment variables
STICKER_PARTNER_ID=550e8400-e29b-41d4-a716-446655440000
STICKER_API_KEY=sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep your API key secret! Never expose it in frontend code, public repositories, or browser network requests.

Authentication Headers

Different endpoints use different authentication headers:

Organization Setup Endpoint

POST /v1/organizations/setup
Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

Partner Handshake Endpoint

POST /v1/partner/handshake
X-API-Key: sk_live_your_api_key
Content-Type: application/json

Code Examples

// Organization Setup - uses Authorization: Bearer
const setupResponse = await fetch('https://api.usesticker.com/v1/organizations/setup', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.STICKER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ /* ... */ })
});

// Partner Handshake - uses X-API-Key
const handshakeResponse = 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({ /* ... */ })
});

import httpx
import os

api_key = os.getenv("STICKER_API_KEY")

# Organization Setup - uses Authorization: Bearer
setup_response = await client.post(
    "https://api.usesticker.com/v1/organizations/setup",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={...}
)

# Partner Handshake - uses X-API-Key
handshake_response = await client.post(
    "https://api.usesticker.com/v1/partner/handshake",
    headers={
        "X-API-Key": api_key,
        "Content-Type": "application/json",
    },
    json={...}
)

Error Responses

401 Unauthorized

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

Common causes:

Missing authentication header
Invalid API key
Using wrong header (Authorization vs X-API-Key)
Using production key in sandbox or vice versa

403 Forbidden

{
  "error": "Forbidden",
  "message": "API key does not have required scope",
  "code": "FORBIDDEN"
}

Common causes:

API key lacks required permissions
Trying to access resources from another partner

Security Best Practices

Server-Side Only

Never expose your API key in client-side code.

// ❌ BAD - API key in frontend
fetch('https://api.usesticker.com/v1/partner/handshake', {
  headers: { 'X-API-Key': 'sk_live_xxx' }  // Exposed!
});

// ✅ GOOD - Call through your backend
fetch('/api/supplies/auth', {
  method: 'POST',
  body: JSON.stringify({ userId })
});

Environment Variables

Store API keys in environment variables:

# .env (never commit!)
STICKER_API_KEY=sk_live_xxxxx

// Read from environment
const apiKey = process.env.STICKER_API_KEY;

Key Rotation

If your key is compromised:

Contact Sticker support immediately
We’ll issue a new key
Update your environment variables
Redeploy your application

Session Tokens vs API Keys

	API Keys	Session Tokens
Used for	Server-to-server API calls	User authentication in iframe
Lifetime	Permanent until rotated	5 minutes
Usage	Unlimited	Single-use
Obtained from	Sticker team	Handshake endpoint
Stored	Environment variables	Never stored (use immediately)

Testing Authentication

# Test Organization Setup endpoint
curl -X POST https://api.usesticker.com/v1/organizations/setup \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{"internalOrgId":"test","organizationName":"Test","internalUserId":"user","user":{"firstName":"Test","lastName":"User","email":"test@example.com"}}'

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

API Reference

Overview

Getting API Credentials

Authentication Headers

Organization Setup Endpoint

Partner Handshake Endpoint

Code Examples

Error Responses

401 Unauthorized

403 Forbidden

Security Best Practices

Session Tokens vs API Keys

Testing Authentication

Next Steps

Organization Setup

Partner Handshake

​Overview

​Getting API Credentials

​Authentication Headers

​Organization Setup Endpoint

​Partner Handshake Endpoint

​Code Examples

​Error Responses

​401 Unauthorized

​403 Forbidden

​Security Best Practices

​Session Tokens vs API Keys

​Testing Authentication

​Next Steps

Organization Setup

Partner Handshake

Overview

Getting API Credentials

Authentication Headers

Organization Setup Endpoint

Partner Handshake Endpoint

Code Examples

Error Responses

401 Unauthorized

403 Forbidden

Security Best Practices

Session Tokens vs API Keys

Testing Authentication

Next Steps