Skip to main content

​
Integrating with a SSO-enabled Workspace

Your app can still authenticate users in a workspace that has Single Sign-On (SSO) enabled. When accessing a protected resource (for example, a project within the workspace), if the user does not have a valid session, the request will fail with a SSO_SESSION_MISSING_OR_EXPIRED_ERROR. Query where the projectId is under a workspace with SSO enabled, and the user does not have a valid session: 
query GetProjectName($projectId: String!) {
  project(id: $projectId) {
    name
  }
}
Will result in this error: 
{
  "errors": [
    {
      "message": "Your workspace SSO session is expired or it does not exist",
      "path": ["project"],
      "extensions": {
        "code": "SSO_SESSION_MISSING_OR_EXPIRED_ERROR",
        "workspaceSlug": "{workspace-short-id}",
        "stacktrace": ["..."],
        "statusCode": 401
      }
    }
  ],
  "data": null
}
To resolve this, the user must authenticate with SSO to obtain a valid session. Redirect the user to: app.speckle.systems/api/v1/workspaces/{workspace-short-id}/sso/auth?challenge=${challenge}&appId={appId}&finalPath={finalPath} Where:
  • worksapce-short-id: The unique short id of the workspace, provided in the error response
  • challenge: Random string generated by your app
  • appId: ID of your registered application given by Speckle. This value is optional, but if provided, the user will be redirected back to the registered domain once authenticated.
  • finalPath: is the path within your app where the user should be redirected after authenticating with SSO. This value is optional, but if provided, the user will be redirected to this path after authenticating with SSO.
Once the user successfully authenticates with SSO, they will be redirected back to your app with a valid session, and the original request will succeed.
Last modified on March 26, 2026