ShellApps ID (Auth)

ShellApps ID is the centralised authentication platform for the entire ShellApps ecosystem, hosted at auth.shellapps.com. Every ShellApps service authenticates through this single identity layer.

How It Works

User → auth.shellapps.com → JWT session → Any ShellApps service

User signs in (email/password or OAuth provider)
Auth issues a signed JWT session token
The token is used across all ShellApps services — Experience, Toolshed, RapidStack, etc.

Key Concepts

JWT Sessions

All sessions are JWT-based. Tokens are short-lived (15 min) with a longer-lived refresh token (30 days). See the API Reference for token endpoints.

// Decoded JWT payload
{
  sub: "user_abc123",
  profileId: "profile_xyz",
  roles: ["builder"],
  exp: 1709312400,
  iss: "auth.shellapps.com"
}

Profiles

Users can have multiple profiles — similar to Discord's server-specific identities. Each profile carries its own display name, avatar, and permissions. Users switch between profiles seamlessly.

Builder Tools Activation

Users with the builder role get access to additional tooling across the platform — editing capabilities in Experience, access to Toolshed integrations, and agent management via RapidStack.

Groups & Permissions

Users belong to groups that control access across the ecosystem. Groups have roles, and roles have granular permissions.

Quick Start

import { ShellAuth } from '@shellapps/auth-client';
 
const auth = new ShellAuth({
  clientId: 'your-app-id',
  redirectUri: 'https://your-app.com/callback',
});
 
// Redirect to login
auth.login();
 
// After callback
const session = await auth.handleCallback();
console.log(session.user.profileId);

API Reference — Endpoints and authentication flows
Profiles — Multi-profile identity system
Groups & Permissions — Access control
OAuth Integration — Third-party app authentication

Architecture API Reference