> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scute.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace Sessions - Cross-App login solution

> Enable seamless user authentication between multiple apps in your workspace

# 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

```bash theme={null}
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)

```json theme={null}
{
  "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

```javascript theme={null}
// 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

| Status | Error                        | Meaning                      |
| ------ | ---------------------------- | ---------------------------- |
| 401    | `workspace_api_key_required` | Invalid workspace API key    |
| 403    | `workspace_access_denied`    | User not member of workspace |
| 404    | `app_not_in_workspace`       | Target 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](https://dashboard.scute.io)
2. Navigate to your workspace settings
3. Generate or copy your Workspace API Key
4. Store it securely in your backend environment variables