Authentication API

The RitualOS ecosystem uses OAuth 2.0 with PKCE for secure authentication. All services authenticate through the central ID Service.

OAuth Endpoints

POST /api/oauth/authorize

Initiates the OAuth 2.0 authorization flow.

POST /api/oauth/token

Exchange authorization code for access token.

Using the API

1. Initialize OAuth Client

2. Handle Callback

After user authorization, they'll be redirected to your redirect_uri with an authorization code:

// In your callback handler
export async function GET(request: Request) {
  const url = new URL(request.url);
  const code = url.searchParams.get('code');
  
  // Exchange code for access token
  const tokenResponse = 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: 'https://yourapp.com/auth/callback',
      client_id: process.env.ID_SERVICE_CLIENT_ID,
      client_secret: process.env.ID_SERVICE_CLIENT_SECRET
    })
  });
  
  const { access_token } = await tokenResponse.json();
  
  // Store access_token securely
  // Redirect user to your app
}

3. Fetch User Claims

Once you have an access token, you can fetch user identity and claims:

System Architecture

The authentication flow across the ecosystem:

Service Integration Map

All ecosystem services connect to the ID Service for authentication:

Scopes

Available OAuth scopes:

Security Best Practices

1. Always use PKCE for public clients (web, mobile)
2. Store tokens securely - use HttpOnly cookies for web apps
3. Validate redirect URIs - only allow whitelisted URLs
4. Use state parameter - prevent CSRF attacks
5. Rotate credentials - regularly refresh access tokens
6. Implement logout - clear tokens on user logout

Error Handling

Common error responses:

// Invalid client
{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

// Invalid grant
{
  "error": "invalid_grant",
  "error_description": "Authorization code is invalid or expired"
}

// Invalid scope
{
  "error": "invalid_scope",
  "error_description": "Requested scope is not allowed"
}

Next Steps

• Learn about issuing credentials
• Explore service APIs
• Read architecture overview