ID Service

The ID Service (id.ritualos.com) is the central identity provider for the entire RitualOS ecosystem. It serves as the single source of truth for all user identities, credentials, and authentication.

Overview

The ID Service is responsible for:

• Identity Management: Creating and managing canonical user identities
• OAuth 2.0 Provider: Handling authentication across all ecosystem services
• Credential Issuance: Verifying and issuing credentials to users
• House & Archetype Assignment: Determining behavioral profiles
• Avatar System: Managing 3D avatar assets
• Wallet Connection: Linking cryptocurrency wallets to identities

Architecture Position

Core Features

1. OAuth 2.0 Authentication

The ID Service implements the OAuth 2.0 Authorization Code flow with PKCE:

// Initialize OAuth
const authUrl = `https://id.ritualos.com/api/oauth/authorize?` +
  `client_id=${clientId}&` +
  `redirect_uri=${encodeURIComponent(redirectUri)}&` +
  `response_type=code&` +
  `scope=identity credentials`;

2. Identity & Passport

Every user in RitualOS has a Passport - their digital identity card containing:

• Identity ID: Unique identifier (e.g., usr_abc123)
• Display Name: User's chosen name
• House: Behavioral profile (Dawn, Zenith, or Twilight)
• Archetype: Playstyle classification (Explorer, Creator, Leader, Guardian)
• Level: Current level (1-100)
• XP: Experience points
• Credentials: Array of earned credentials

3. Houses

Houses are not chosen - they're discovered through behavioral patterns:

4. Archetypes

Archetypes describe how users interact with the system:

5. Credential System

Credentials are verifiable attestations about a user's achievements and behaviors:

API Endpoints

Authentication

• POST /api/oauth/authorize - Initiate OAuth flow
• POST /api/oauth/token - Exchange code for token
• GET /api/claims - Get user identity claims

Identity

• GET /api/me - Get current user info
• PATCH /api/me/username - Update username
• GET /api/me/passport - Get full passport data

Credentials

• GET /api/credentials - List user credentials
• POST /api/credentials/issue - Issue a credential (admin)
• GET /api/credentials/[id] - Get credential details

Wallets

• GET /api/wallets - List linked wallets
• POST /api/wallets/link - Link new wallet
• DELETE /api/wallets/[address] - Unlink wallet

Database Schema

The ID Service uses the following main models:

model Identity {
  id            String        @id
  displayName   String
  house         House
  archetype     Archetype
  level         Int           @default(1)
  xp            Int           @default(0)
  createdAt     DateTime      @default(now())
  updatedAt     DateTime      @updatedAt
  
  sessions      Session[]
  wallets       Wallet[]
  credentials   CredentialAward[]
}

model CredentialAward {
  id            String        @id
  identityId    String
  credentialType String
  claims        Json
  issuedAt      DateTime      @default(now())
  
  identity      Identity      @relation(fields: [identityId])
}

model Session {
  id            String        @id
  identityId    String
  token         String        @unique
  expiresAt     DateTime
  
  identity      Identity      @relation(fields: [identityId])
}

Environment Variables

Required environment variables for the ID Service:

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/id_service

# OAuth
JWT_SECRET=your-secret-key-min-32-chars
SESSION_SECRET=your-session-secret-min-32-chars

# API Keys (for credential issuance)
ISSUER_API_KEY=rit_sk_your_secret_key

# OAuth Clients
OAUTH_REDIRECT_URI=https://yourapp.com/auth/callback

Integration Examples

Web App Integration

// app/auth/callback/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function GET(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams;
  const code = searchParams.get('code');
  
  // Exchange code for token
  const tokenRes = await fetch('https://id.ritualos.com/api/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      grant_type: 'authorization_code',
      code,
      redirect_uri: process.env.REDIRECT_URI,
      client_id: process.env.CLIENT_ID,
      client_secret: process.env.CLIENT_SECRET
    })
  });
  
  const { access_token } = await tokenRes.json();
  
  // Fetch user claims
  const claimsRes = await fetch('https://id.ritualos.com/api/claims', {
    headers: { 'Authorization': `Bearer ${access_token}` }
  });
  
  const claims = await claimsRes.json();
  
  // Create session and redirect
  // ... your session logic
  
  return NextResponse.redirect('/dashboard');
}

Service Connections

The ID Service connects to all other services:

Testing

Local Development

# Start the ID Service locally
cd id.ritualos.com
npm run dev

# Service runs on port 7000
# Visit: http://localhost:7000

Test OAuth Flow

1. Start your app with the correct OAuth config
2. Click "Sign In"
3. Complete the OAuth flow
4. Check your passport at /api/me/passport

Troubleshooting

Common Issues

Issue: "Invalid redirect_uri"

• Solution: Add your redirect URI to the OAuth client config

Issue: "Authorization code expired"

• Solution: Code must be exchanged within 5 minutes

Issue: "Invalid credentials"

• Solution: Check CLIENT_ID and CLIENT_SECRET are correct

Next Steps

• Learn about OAuth integration
• Explore credential types
• Understand house assignment