Skip to main content

identity-service

Sign-in, sessions, and company directories for your Shellui app, in one service you host.

identity-service is the authentication backend for Shellui (backend.type: "shellui"). It signs people in with OAuth, a magic link, or SAML, issues the JSON Web Tokens (JWTs) your shell and APIs verify, and keeps each company's members, groups, and access rules. It is a Django app, published as the shellui/identity-service Docker image.

Sign-in providers​

Each company picks its own sign-in methods and adds its own provider credentials in Shellui admin. Magic link sign-in works with no provider at all.

15 OAuth and OpenID Connect providers plus SAML 2.0, configured per company in Shellui admin.

What identity-service does​

identity-service covers six areas. Each card opens the guide for that area.

How sign-in works​

A Shellui shell never talks to a provider directly. identity-service runs the whole flow and returns tokens to the shell:

  1. The shell sends the browser to GET /api/v1/authorize with company_id, redirect_to, and an S256 code_challenge.
  2. identity-service redirects to the provider named in provider, or shows the company's providers to pick from when it is not set.
  3. The provider returns to /api/v1/oauth/callback. identity-service exchanges the code server-side and applies the company access rules.
  4. identity-service redirects to redirect_to?shellui_auth_code=…. A web target is an origin on the company allowlist. A desktop target uses a scheme in the company list (Desktop apps).
  5. The shell host exchanges that one-time code at POST /api/v1/oauth/session with code_verifier and the shell Origin. It keeps the tokens. See Shell host session.

Your own APIs verify the access token with the public keys at /.well-known/jwks.json, without sharing any secret with identity-service. Details are in OAuth login and JWT and JWKS.

Find your guide​

Pick the row that matches what you are doing today:

You want toStart with
Deploy identity-service with Docker and RedisRun identity-service, then Configuration
Add Google, GitHub, Microsoft, or another providerOAuth providers
Let people sign in without a providerMagic link
Sign in from a desktop appDesktop apps
Sign in the Shellui CLI on another deviceCLI device login
Connect a company's Okta or Entra IDSAML single sign-on and SCIM provisioning
Trust one upstream identity provider, or be that providerInstance roles
Restrict who can join a companyCompany access
Verify Shellui tokens in another serviceJWT and JWKS
Connect a headless MCP agent without pasting a tokenMCP device login
Run automation when users join or leaveWebhooks and n8n
Audit sign-ins and changesEvent log
Harden a production installSecurity hardening
Upgrade from an older releaseUpgrade notes

Endpoints at a glance​

These are the endpoints you meet first. The full, interactive reference is served by each install at /api/docs/ (OpenAPI).

EndpointPurpose
GET /api/v1/settings?company_id=…Sign-in methods and providers enabled for a company
GET /api/v1/authorizeStart a sign-in
POST /api/v1/oauth/sessionExchange the one-time shellui_auth_code for tokens
POST /api/v1/token?grant_type=refresh_tokenRefresh a session
GET /api/v1/userCurrent user profile and user_metadata
GET /.well-known/jwks.jsonPublic keys for token verification
GET /health/liveLiveness probe for load balancers

Release and source​

These docs describe identity-service 0.9.2. Source, issues, and the changelog are on GitHub. Release tags and the Docker publish steps are in Releases.

These pages are built from the docs/ folder of the repository by shellui/shellui and published on docs.shellui.com. To preview an edit with live reload, clone shellui next to identity-service and run:

cd ../shellui
pnpm install
DOCS_SERVICES=identity pnpm docs:start