Profiles

The profile system lets users maintain multiple identities within ShellApps — similar to how Discord users have different server profiles.

Concepts

One User, Many Profiles

A single ShellApps ID account can have multiple profiles. Each profile has its own:

Display name and avatar
Group memberships and permissions
Active state — only one profile is active at a time

Active Profile

Your active profile determines your identity across all ShellApps services. When you interact with Experience, Toolshed, or any other service, they see your active profile.

User Account
├── Profile A (active) ← This is "you" right now
│   ├── displayName: "Alex"
│   ├── groups: [team-alpha, builders]
│   └── roles: [builder, admin]
├── Profile B
│   ├── displayName: "Alex (Personal)"
│   ├── groups: [personal-space]
│   └── roles: [viewer]

Profile Switching

Switching profiles issues a new JWT with the selected profile's context. All subsequent requests use the new profile's identity and permissions.

const response = await fetch('https://auth.shellapps.com/api/v1/profiles/profile_abc/activate', {
  method: 'PUT',
  headers: { Authorization: `Bearer ${token}` },
});
 
const { accessToken } = await response.json();
// Use this new token — it contains the switched profile

Data Model

interface Profile {
  id: string;            // "profile_xyz"
  userId: string;        // Parent user account
  displayName: string;
  avatar?: string;       // URL to avatar image
  isActive: boolean;
  roles: string[];       // ["builder", "admin"]
  groups: Group[];       // Group memberships
  metadata: Record<string, unknown>;
  createdAt: string;     // ISO 8601
  updatedAt: string;
}

Use Cases

Work vs Personal — Keep builder/admin tools on one profile, casual browsing on another
Team contexts — Different profiles for different groups and projects
Testing — Use a separate profile to test permission-restricted views

API Reference — Profile endpoints
Groups & Permissions — How profiles interact with groups
OAuth — Profile context in OAuth tokens

API Reference Groups & Permissions