Skip to main content
SSO (Single Sign-On) lets users authenticate through an external identity provider (IdP) configured for their tenant. Each tenant has its own IdP configuration — you cannot use SSO endpoints without a tenant that has SSO enabled.

​
Supported IdPs

The SupportedIdP enum lists the IdPs you can configure at the tenant level:
ValueDescription
OAUTH2Standard OAuth2 / OpenID Connect provider (e.g. Google)
FANWEI_E9FanWei E9 enterprise IdP with directory sync
The IdpType used in query parameters covers the full set of provider identifiers: PASSWORD, GOOGLE, TENANT.
SSO configuration is managed at the tenant level by tenant owners or admins. These endpoints handle the runtime authentication flow, not IdP configuration.

​
Initiate SSO


POST https://api-staging.knowledgestack.ai/v1/auth/sso/initiate Start an SSO flow for a given provider and optional tenant. Returns a redirect_url that you should direct the user to in order to complete authentication with the IdP.

​
Query parameters

​
provider
string
required
The IdP to initiate SSO with. One of the IdpType values (e.g. GOOGLE).
​
tenant_id
string (uuid)
The tenant to authenticate against. Required for tenant-specific IdPs.

​
Response 200

​
redirect_url
string
The URL to redirect the user to in order to complete the SSO flow with the IdP.

​
Example

curl -X POST "https://api-staging.knowledgestack.ai/v1/auth/sso/initiate?provider=GOOGLE&tenant_id=<tenant-id>" \
  -H "Authorization: Bearer <your-api-key>"

{
  "redirect_url": "https://accounts.google.com/o/oauth2/auth?client_id=..."
}

​
SSO login redirect handler


GET https://api-staging.knowledgestack.ai/v1/auth/sso/{tenant_id}/signin Entry-point redirect handler for tenant-specific SSO login. Resolves the tenant’s configured IdP and dispatches the browser to the appropriate provider. Sets the ks_uat cookie and redirects to the frontend on completion. This endpoint is typically called by the frontend — it is not a JSON API endpoint. The browser follows the redirect chain through the IdP and back.

​
Path parameters

​
tenant_id
string (uuid)
required
The tenant whose IdP configuration to use.

​
Query parameters

​
redirect
string
Post-login redirect path within the application. Defaults to "" (root).

​
Response 307

Temporary redirect to the IdP’s authorization endpoint.

​
Example

# Typically opened in a browser, not called with curl
curl -v "https://api-staging.knowledgestack.ai/v1/auth/sso/<tenant-id>/signin?redirect=/dashboard"

​
OAuth2 callback


GET https://api-staging.knowledgestack.ai/v1/auth/sso/oauth2/callback OAuth2 callback handler. The IdP redirects the user here after authorization. This endpoint exchanges the authorization code for user details, sets the ks_uat cookie, and returns the authenticated user. You do not call this endpoint directly — the IdP calls it as part of the OAuth2 authorization code flow.

​
Query parameters

​
provider
string
required
The IdP that issued the callback. Must match the IdpType used to initiate the flow.
​
code
string
Authorization code returned by the IdP.
​
state
string
State parameter for CSRF protection, returned by the IdP.
​
error
string
Error code if the IdP denied authorization.
​
error_description
string
Human-readable error description from the IdP.
​
tenant_id
string (uuid)
Tenant ID to scope the session to.

​
Response 200

Returns a UserResponse on successful authentication.
​
id
string (uuid)
User ID.
​
email
string
User’s email address.
​
first_name
string
First name.
​
last_name
string
Last name.
​
idp_type
string
Identity provider type. One of PASSWORD, GOOGLE, TENANT.
​
current_tenant_id
string (uuid)
The tenant the user is currently scoped to.
​
current_tenant_role
string
The user’s role in the current tenant.
​
default_tenant_id
string (uuid)
The user’s default tenant.

​
Directory sync


POST https://api-staging.knowledgestack.ai/v1/auth/sso/{tenant_id}/directory_sync Trigger a directory synchronization for a FanWei E9 tenant. Syncs users from the enterprise IdP into Knowledge Stack — creating, updating, activating, or deactivating accounts to match the IdP’s directory.
This endpoint requires either a tenant OWNER/ADMIN UAT or an admin API key. It is specific to tenants configured with the FANWEI_E9 IdP.

​
Path parameters

​
tenant_id
string (uuid)
required
The tenant to synchronize.

​
Response 200

Returns a DirectorySyncResponse summarizing the sync operation.
​
users_created
integer
Number of new user accounts created.
​
users_updated
integer
Number of existing accounts updated.
​
users_activated
integer
Number of previously deactivated accounts reactivated.
​
users_deactivated
integer
Number of accounts deactivated because they were removed from the IdP.
​
users_skipped
integer
Number of directory entries skipped (e.g. already up to date).
​
warnings
string[]
Non-fatal warnings encountered during sync.
​
errors
string[]
Errors encountered during sync (entries that failed to process).

​
Example

curl -X POST https://api-staging.knowledgestack.ai/v1/auth/sso/<tenant-id>/directory_sync \
  -H "Authorization: Bearer <your-api-key>"

{
  "users_created": 5,
  "users_updated": 12,
  "users_activated": 1,
  "users_deactivated": 2,
  "users_skipped": 30,
  "warnings": [],
  "errors": []
}