Skip to main content

Implementing Single Sign-On

If you have not created an API Client, please visit Create an API Client before continuing.

caution

If you are a POS API partner, please use the POS API Merchant Onboarding flow to generate an SSO Login for a seamless experience. POS API Merchant Onboarding

Request a Token from the API​

To begin, request a token using your created API. For more information on requesting tokens, click here.

Please make sure you do not expose API Client credentials to the browser.

Generate an SSO Login Token​

To initiate an SSO login, make a POST request to /white-label/generate-session with the following required user details:

Organization Details​

  • provider_org_id (required) - Your internal organization identifier that groups users together
    • All users with the same provider_org_id will share access to the same locations, data, and integrations
    • Use consistent identifiers across your system (e.g., franchise IDs, business registration numbers)
  • role (required) - The user's role within the organization:
    • "owner" - Full administrative access to all organization features
    • "admin" - Administrative access with some restrictions
    • "manager" - Management access to specific locations or functions
    • "team_member" - Basic operational access
    • "custom" - Custom role with specific permissions

User Details​

  • email (required) - The user's email address
  • full_name (required) - The user's full name
  • phone_number (required) - The user's phone number

Example Request​

POST /white-label/generate-session
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "provider_org_id": "restaurant_chain_abc_123",
  "role": "manager",
  "email": "sarah.manager@restaurantchain.com",
  "full_name": "Sarah Johnson",
  "phone_number": "+1-555-123-4567"
}

Example Response​

{
  "sso_login_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

The API will return a sso_login_token that can only be used once. Subsequent attempts to use the same token will result in a sso_token_redeemed error.

Redirect to the White Label Application​

To exchange your sso_login_token for a session, redirect users to a one-time URL built using the code query parameter, like <WHITE_LABEL_DOMAIN>/redirect/sso?code=<SSO_LOGIN_TOKEN>.

Understanding Organizations and User Grouping​

Before implementing SSO, it's important to understand how Stream organizes users and data access through the concept of Organizations.

What is an Organization?​

An Organization in Stream represents a business entity (like a restaurant, retail chain, or franchise) that groups users together to:

  • Share access to the same locations, menus, and order data
  • Collaborate on business operations with appropriate role-based permissions
  • Maintain data consistency across all users within the organization

How provider_org_id Works​

The provider_org_id is your internal identifier that determines which users belong to the same organization. Users with the same provider_org_id will:

✅ Share the same organization and can collaborate on:

  • Location management and settings
  • Menu configurations and updates
  • Order history and analytics
  • Integration configurations (POS, DSP connections)

✅ Access the same data based on their assigned role permissions

Example Organization Scenarios​

Scenario 1: Multi-Location Restaurant Chain

McDonald's Franchise Group (provider_org_id: "mcdonalds_group_123")
├── John (owner) - Can manage all locations and users
├── Sarah (manager) - Can manage specific locations
└── Mike (team_member) - Can view orders and basic operations

Scenario 2: Independent Restaurant

Tony's Pizza (provider_org_id: "tonys_pizza_main")
├── Tony (owner) - Full access to restaurant operations
└── Lisa (admin) - Can manage orders and menu updates

Scenario 3: Separate Business Entities

Different provider_org_ids = Separate organizations:
- Tony's Pizza (provider_org_id: "tonys_pizza_main")
- Maria's Cafe (provider_org_id: "marias_cafe_001")
- (These cannot see each other's data)

Best Practices for provider_org_id​

Organization ID Guidelines
  • Use stable identifiers: Choose IDs that won't change over time (avoid user-generated names)
  • Be consistent: Use the same format across your entire system
  • Include context: Consider prefixing with business type or system identifier
  • Plan for scale: Design IDs that work for single locations and multi-location businesses

Good Examples:

  • franchise_mcdonalds_store_001
  • independent_tonys_pizza_main
  • chain_starbucks_region_west_123
  • corp_id_12345_location_all

Avoid:

  • Changing IDs when business names change
  • Using sequential numbers that might conflict
  • Including personally identifiable information

API Reference - Generate SSO Session

Conclusion​

After completing the steps above, place this process behind an authenticated endpoint and button within your portal. This will allow your users to log in to your white label application with a single click.

Remember that consistent use of provider_org_id is crucial for maintaining proper data isolation and enabling collaboration within organizations. Users with the same provider_org_id will automatically be grouped together and can access shared business data and integrations.