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:
- The shell sends the browser to
GET /api/v1/authorizewithcompany_id,redirect_to, and an S256code_challenge. - identity-service redirects to the provider named in
provider, or shows the company's providers to pick from when it is not set. - The provider returns to
/api/v1/oauth/callback. identity-service exchanges the code server-side and applies the company access rules. - 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). - The shell host exchanges that one-time code at
POST /api/v1/oauth/sessionwithcode_verifierand the shellOrigin. 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 to | Start with |
|---|---|
| Deploy identity-service with Docker and Redis | Run identity-service, then Configuration |
| Add Google, GitHub, Microsoft, or another provider | OAuth providers |
| Let people sign in without a provider | Magic link |
| Sign in from a desktop app | Desktop apps |
| Sign in the Shellui CLI on another device | CLI device login |
| Connect a company's Okta or Entra ID | SAML single sign-on and SCIM provisioning |
| Trust one upstream identity provider, or be that provider | Instance roles |
| Restrict who can join a company | Company access |
| Verify Shellui tokens in another service | JWT and JWKS |
| Connect a headless MCP agent without pasting a token | MCP device login |
| Run automation when users join or leave | Webhooks and n8n |
| Audit sign-ins and changes | Event log |
| Harden a production install | Security hardening |
| Upgrade from an older release | Upgrade 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).
| Endpoint | Purpose |
|---|---|
GET /api/v1/settings?company_id=… | Sign-in methods and providers enabled for a company |
GET /api/v1/authorize | Start a sign-in |
POST /api/v1/oauth/session | Exchange the one-time shellui_auth_code for tokens |
POST /api/v1/token?grant_type=refresh_token | Refresh a session |
GET /api/v1/user | Current user profile and user_metadata |
GET /.well-known/jwks.json | Public keys for token verification |
GET /health/live | Liveness 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