Skip to main content

​
Workspace Sessions

Workspace Sessions provide a simple Single Sign-On (SSO) solution for users to seamlessly move between multiple apps within the same workspace without re-authentication.

​
Use Cases

  • Multi-app ecosystems: Users authenticated in your main app can access related tools/services
  • Marketplace platforms: Vendors authenticated in the marketplace can access their seller dashboard
  • Admin panels: Users can switch between customer-facing app and admin interface
  • Microservices: Frontend can authenticate users across different backend services

​
How It Works

The workspace session flow exchanges a user’s existing session in one app for a new session in another app within the same workspace: 
User in App A → Workspace Session API → New session in App B

​
Authentication Flow

  1. User is already authenticated in App A within your workspace
  2. Your backend calls the workspace session endpoint with:
    • User’s access token (from App A)
    • Workspace API key (from dashboard)
    • Target app ID (App B)
  3. Receive new session tokens for the user in App B
  4. User is now authenticated in App B without manual login

​
Implementation

​
Prerequisites

  • Multiple apps in the same workspace
  • Workspace API key from your Scute dashboard
  • User authenticated in source app

​
API Request

POST https://api.scute.io/v1/workspaces/WORKSPACE_ID/sessions
Authorization: Bearer <WORKSPACE_API_KEY>
X-Authorization: Bearer <USER_ACCESS_TOKEN>
Content-Type: application/json

{
  "app_id": "app_target_app_id"
}

​
Response (Scute Session)

{
  "access": "eyJhbGciOiJSUzI1NiJ9...",
  "refresh": "eyJhbGciOiJSUzI1NiJ9...",
  "csrf": "ttRd+JqyT...",
  "access_expires_at": "2025-07-11T18:46:43.000+03:00",
  "refresh_expires_at": "2025-07-18T17:46:43.000+03:00",
  "user_id": "90c58919-b3f0-450b-8d3d-c57e4f416970",
  "key_id": "43c742a-9e4c-4a4d-92e7-67ee2e028e55_1750984640"
}

​
Example: Marketplace to Seller Dashboard

// User clicks "Go to Seller Dashboard" in marketplace
async function redirectToSellerDashboard(userToken, workspaceId) {
  try {
    const response = await fetch(`/v1/workspaces/${workspaceId}/sessions`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${WORKSPACE_API_KEY}`,
        'X-Authorization': `${userToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        app_id: 'app id'
      })
    });

    const tokens = await response.json();
    
    // Redirect to seller dashboard with new tokens
    // You now have: tokens.access, tokens.refresh, tokens.csrf, tokens.user_id, tokens.key_id, store it somewhere secure
    window.location.href = `https://sellers.marketplace.com`;
  } catch (error) {
    console.error('SSO failed:', error);
  }
}

​
Security Considerations

​
Access Control

  • Workspace API key ensures only authorized apps can create cross-app sessions
  • User token validation confirms the user exists and has valid authentication
  • App workspace validation prevents cross-workspace token exchange

​
Token Scope

  • Tokens are app-specific - cannot be used across different apps
  • Each workspace uses separate RSA keys for token signing
  • Sessions maintain user context but are scoped to the target app

​
Error Handling

StatusErrorMeaning
401workspace_api_key_requiredInvalid workspace API key
403workspace_access_deniedUser not member of workspace
404app_not_in_workspaceTarget app not in workspace

​
Best Practices

  1. Store workspace API key securely - Never expose in client-side code
  2. Validate user permissions - Ensure user should have access to target app
  3. Handle errors gracefully - Fallback to standard login if SSO fails
  4. Use HTTPS only - Protect tokens in transit
  5. Implement token refresh - Handle token expiration seamlessly

​
Getting Your Workspace API Key

  1. Go to your Scute Dashboard
  2. Navigate to your workspace settings
  3. Generate or copy your Workspace API Key
  4. Store it securely in your backend environment variables