Authentication Service¶

A comprehensive OAuth 2.0 authentication service supporting multiple authentication methods including standard OAuth 2.0, GitHub OAuth, Google OAuth, and secure Agent-to-Agent (A2A) authentication with advanced cryptographic security features.

Quick Start¶

Choose Your Authentication Method¶

Method	Use Case	User Interaction	Token Type	Documentation
OAuth 2.0	User login with email/password	Required	Access + Refresh	API Reference
Two-Factor (2FA/OTP)	Enhanced security with TOTP codes	Required	Access + Refresh	2FA Guide
GitHub OAuth	Social login via GitHub	Required	Access + Refresh	GitHub Guide
Google OAuth	Social login via Google	Required	Access + Refresh	API Reference
A2A Authentication	Machine-to-machine authentication	None	Access Only	A2A Guide
Agent Secret Tokens	Cryptographically secure agent validation	None	Encrypted	Agent Security Guide

Complete Documentation (17 Files)¶

📖 Main Documentation Hub: docs/auth_servic../index.md - Start here for complete navigation

🔧 API Reference: Complete API Reference - All endpoints and parameters

🛠️ Testing: Postman Collection - 6000+ lines of comprehensive tests

Development Setup¶

Using Docker (Recommended)¶

Requirements: - Docker - docker-compose

Setup:

git clone <repository-url>
cd authentication_ms
docker-compose build && docker-compose up

Native Setup¶

Requirements: - Ruby version: 3.0.0 - PostgreSQL 9.4+ Installation Guide - Bundler Installation Guide

Setup:

# Quick setup
bin/setup

# Or manual setup
gem install bundler
bundle install
cp env.sample .env  # Edit with your configuration
# Edit app/services/company_config.json for branding customization
bundle exec rake db:create db:migrate
bin/rails s

🧪 Testing¶

Run Tests¶

# Comprehensive test suite (recommended)
./scripts/run_tests.sh

# Quick development feedback
./scripts/run_tests.sh --quick

# Category-specific testing
./scripts/run_tests.sh --core-only      # Core authentication
./scripts/run_tests.sh --a2a-only       # Agent-to-Agent
./scripts/run_tests.sh --integration-only  # Integration tests
./scripts/run_tests.sh --validation-only   # JWT validation

# Individual test scripts
./scripts/test_core_fast.sh             # Fast core tests
./scripts/test_a2a_auth.sh              # A2A authentication
ruby scripts/test_jwt_validation.rb     # JWT validation

# Docker
docker-compose -f docker-compose-test.yml build && docker-compose -f docker-compose-test.yml run test

# Native RSpec
bundle exec rspec

📚 Complete Test Scripts Guide: docs/TEST_SCRIPTS_GUIDE.md - Comprehensive guide to all 10 test scripts

API Testing¶

Use the comprehensive Postman Collection for testing all endpoints.

Configuration¶

Company Branding Configuration¶

The service uses a centralized JSON configuration file for all company branding settings. This approach provides a clean, maintainable way to customize the application's branding without cluttering environment variables.

Configuration File: app/services/company_config.json

{
  "product": "Scoutica",
  "product_url": "scoutica.com",
  "sender_email": "noreply@scoutica.com",
  "logo_url": "https://scoutica.com/logo.png",
  "sender_text": "Best regards,<br>The Scoutica Team",
  "product_text": "Scoutica is your comprehensive authentication and user management platform. For support, contact support@scoutica.com.",
  "team_name": "Scoutica Team",
  "frontend_url": "https://scoutica.com",
  "google_app_name": "traylinx-oauth",
  "callback_uri": "http://localhost:3000/oauth2callback"
}

Benefits: - ✅ Centralized Configuration: All branding in one JSON file - ✅ Easy Customization: Modify branding without code changes - ✅ Version Controlled: JSON file is tracked in git - ✅ Fallback Safety: Defaults if JSON file is missing - ✅ Clean Environment: No branding clutter in environment variables

Usage:

# Access configuration in Ruby code
CompanyConfig.product          # => "Scoutica"
CompanyConfig.sender_email     # => "noreply@scoutica.com"
CompanyConfig.frontend_url     # => "https://scoutica.com"

Environment Variables¶

# Database
DATABASE_NAME=o_auth_ms
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=password

# Application
RAILS_MAX_THREADS=5
AUTH_SECRET=your_secret_key

# AWS (if using)
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=eu-west-1

# OAuth Applications
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

# Agent Token Security Configuration (optional - uses defaults if not set)
AGENT_SECRET_TOKEN_VALIDITY_WINDOW=3600          # Token validity: 1 hour
AGENT_SECRET_TOKEN_CLOCK_SKEW_TOLERANCE=300      # Clock skew: 5 minutes  
AGENT_SECRET_TOKEN_PBKDF2_ITERATIONS=10000       # Encryption strength

# Agent Rate Limiting Configuration (optional - uses defaults if not set)
AGENT_RATE_LIMIT_WINDOW_SIZE=3600                # Rate limit window: 1 hour
AGENT_RATE_LIMIT_MAX_REQUESTS=100                # Max requests per hour
AGENT_RATE_LIMIT_BURST_WINDOW_SIZE=60            # Burst window: 1 minute
AGENT_RATE_LIMIT_BURST_MAX_REQUESTS=10           # Max burst requests

# Agent Activity Monitoring Configuration (optional - disabled by default)
# See "Agent Activity Monitoring" section below for complete documentation
AGENT_ACTIVITY_LOGGING_ENABLED=false             # Enable activity monitoring
AGENT_ACTIVITY_LOG_BODIES=false                  # Log request/response bodies
AGENT_ACTIVITY_EXCLUDE_PATHS=/health,/metrics,/favicon.ico
AGENT_ACTIVITY_MAX_BODY_SIZE=10000               # Max request body size (bytes)
AGENT_ACTIVITY_MAX_RESPONSE_SIZE=100000          # Max response body size (bytes)
AGENT_ACTIVITY_BATCH_SIZE=100                    # Batch size for bulk inserts
AGENT_ACTIVITY_FLUSH_INTERVAL=5                  # Flush interval (seconds)

# Note: Company branding is configured in app/services/company_config.json
# See "Company Branding Configuration" section above for details

💡 Agent Security Variables Explained: - These environment variables control the Agent-to-Agent (A2A) authentication security - Token Security: Controls how long tokens are valid and encryption strength - Rate Limiting: Prevents abuse with configurable request limits
- All are optional - the system uses secure defaults if not configured - Full documentation: Agent Token Security Configuration

🔒 Two-Factor Authentication (2FA/OTP)¶

The service includes built-in support for Time-based One-Time Password (TOTP) two-factor authentication compatible with popular authenticator apps.

🔑 How OTP Authentication Works¶

When a user has 2FA enabled, the authentication flow requires both password and OTP code:

# Standard login (password only)
curl -X POST http://localhost:3000/oauth/token \
  -H "Api-Key: your_api_key" \
  -d "username=user@example.com" \
  -d "password=user_password" \
  -d "grant_type=password" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret"

# 2FA login (password + OTP code)
curl -X POST http://localhost:3000/oauth/token \
  -H "Api-Key: your_api_key" \
  -d "username=user@example.com" \
  -d "password=user_password" \
  -d "otp_code=123456" \
  -d "grant_type=password" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret"

📱 User Database Schema¶

Each user has two OTP-related fields:

# app/models/user.rb
class User < ApplicationRecord
  has_one_time_password  # Enables TOTP functionality

  # Database fields:
  # otp_secret_key         :string   - TOTP secret (auto-generated)
  # otp_required_for_login :boolean  - Enable/disable 2FA per user
end

Authentication Logic Flow¶

The system implements three authentication paths:

PATH 1 - OTP Required but Missing: Returns error provide_valid_code
PATH 2 - OTP Authentication: Validates both password and OTP code
PATH 3 - Standard Authentication: Password-only (when 2FA disabled)

# Authentication logic in config/initializers/doorkeeper.rb
if user && user.otp_required_for_login.present? && params[:otp_code].blank?
  # PATH 1: 2FA required but no OTP provided
  raise Doorkeeper::Errors::DoorkeeperError, 'provide_valid_code'

elsif user && user.otp_required_for_login.present? && 
      params[:otp_code].present? && user.authenticate_otp(params[:otp_code], drift: 60)
  # PATH 2: Successful 2FA authentication
  user

elsif user && user.otp_required_for_login.blank?
  # PATH 3: Standard password authentication  
  user&.authenticate(params[:password])
end

Error Handling¶

The system provides specific error messages for OTP scenarios:

Error Code	Message	Description
`provide_valid_code`	"Please enter valid 2fa code"	2FA is enabled but no OTP code provided
`invalid_code`	"Invalid 2fa code"	OTP code is incorrect or expired

Implementation Features¶

✅ TOTP Standard: RFC 6238 compliant time-based codes
✅ Drift Tolerance: 60-second window for clock synchronization
✅ Authenticator App Support: Compatible with Google Authenticator, Authy, 1Password, etc.
✅ Per-User Control: Individual enable/disable via otp_required_for_login
✅ Automatic Secret Generation: TOTP secrets auto-generated via active_model_otp gem
✅ Secure Integration: Built into OAuth 2.0 flow with proper error handling

Managing User 2FA Status¶

# Enable 2FA for a user
user = User.find_by(email: 'user@example.com')
user.update(otp_required_for_login: true)

# Generate QR code URI for authenticator app setup
user.provisioning_uri(user.email, issuer: 'YourApp')

# Disable 2FA
user.update(otp_required_for_login: false)

# Verify OTP code
user.authenticate_otp('123456', drift: 60)  # Returns true/false

📱 Authenticator App Setup¶

Enable 2FA for user in database: otp_required_for_login: true
Generate QR Code using user.provisioning_uri(user.email, issuer: 'YourApp')
User scans QR code with authenticator app (Google Authenticator, Authy, etc.)
User enters first code to verify setup
Subsequent logins require both password and current TOTP code

💡 Note: The current implementation requires manual 2FA management through the database. API endpoints for 2FA setup/management would be a valuable enhancement.

Agent Activity Monitoring¶

The service includes a comprehensive Agent Activity Monitoring System that provides persistent storage, query APIs, real-time monitoring, and external integrations for all agent user activities.

🎯 What is Agent Activity Monitoring?¶

Agent Activity Monitoring enables developers with multiple agentic applications to:

Track all activities - Every API call made by agent users is logged with full context
Query historical data - Programmatically query logs via REST API with filtering and pagination
Real-time monitoring - WebSocket streaming for live activity monitoring
Export data - Export logs in JSON, CSV, or JSONL formats for analysis
View metrics - Aggregated metrics and analytics for agent performance
Integrate with tools - Webhooks, Datadog, Prometheus, and Grafana integrations
Multi-tenant SaaS - Per-user configuration with custom retention policies and integrations

Quick Start¶

1. Enable Agent Activity Monitoring¶

# In your .env file
AGENT_ACTIVITY_LOGGING_ENABLED=true
AGENT_ACTIVITY_LOG_BODIES=true  # Optional: log request/response bodies

2. Run Database Migrations¶

bundle exec rake db:migrate

This creates the partitioned agent_activity_logs table with automatic monthly partitioning.

3. Query Your Agent's Activities¶

# Get all activities for your agent
curl "http://localhost:3000/oauth/agent/activity/logs" \
  -H "Authorization: Bearer YOUR_AGENT_TOKEN" \
  -H "Api-Key: your_api_key"

# Get metrics for the last 7 days
curl "http://localhost:3000/oauth/agent/activity/metrics?group_by=day" \
  -H "Authorization: Bearer YOUR_AGENT_TOKEN" \
  -H "Api-Key: your_api_key"

# Export to CSV
curl "http://localhost:3000/oauth/agent/activity/export?format=csv" \
  -H "Authorization: Bearer YOUR_AGENT_TOKEN" \
  -H "Api-Key: your_api_key" > agent_activity.csv

Available Endpoints¶

Endpoint	Method	Description
`/oauth/agent/activity/logs`	GET	Query logs with filtering, pagination, sorting
`/oauth/agent/activity/logs/:id`	GET	Get single log by ID
`/oauth/agent/activity/metrics`	GET	Aggregated metrics and analytics
`/oauth/agent/activity/export`	GET	Export logs (JSON, CSV, JSONL)
`/oauth/user/activity/config`	GET/PUT	Manage per-user retention policies
`/oauth/user/integrations`	GET/POST/PUT/DELETE	Manage webhooks and external integrations

Configuration Reference¶

Core Settings¶

# Feature Flags
AGENT_ACTIVITY_LOGGING_ENABLED=false       # Enable/disable activity logging
AGENT_ACTIVITY_LOG_BODIES=false            # Log request/response bodies (default: off)
AGENT_ACTIVITY_EXCLUDE_PATHS=/health,/metrics,/favicon.ico  # Comma-separated paths to exclude

# Size Limits (in bytes)
AGENT_ACTIVITY_MAX_BODY_SIZE=10000         # Max request body size: 10KB
AGENT_ACTIVITY_MAX_RESPONSE_SIZE=100000    # Max response body size: 100KB

# Batch Processing
AGENT_ACTIVITY_BATCH_SIZE=100              # Number of logs per batch insert
AGENT_ACTIVITY_FLUSH_INTERVAL=5            # Seconds between batch flushes

Per-User Configuration API¶

# Enable per-user configuration management
AGENT_ACTIVITY_USER_CONFIG_ENABLED=true              # Users can manage their own settings
AGENT_ACTIVITY_INTEGRATIONS_ENABLED=true             # Users can configure integrations
AGENT_ACTIVITY_MAX_INTEGRATIONS_PER_USER=10          # Max integrations per user
AGENT_ACTIVITY_MAX_WEBHOOKS_PER_USER_PER_HOUR=1000   # Rate limit for webhooks
AGENT_ACTIVITY_MAX_RETENTION_DAYS=730                # Max retention: 2 years

System Default Retention Policies¶

These are system defaults used when users haven't configured custom retention. Users can override these via API: PUT /oauth/user/activity/config/retention

AGENT_ACTIVITY_DEFAULT_RETENTION_DAYS=90              # General default: 90 days
AGENT_ACTIVITY_DEFAULT_RETENTION_AUTHENTICATION=365   # Authentication logs: 1 year
AGENT_ACTIVITY_DEFAULT_RETENTION_INTROSPECTION=90     # Token introspection: 90 days
AGENT_ACTIVITY_DEFAULT_RETENTION_A2A_RPC=30           # A2A RPC calls: 30 days
AGENT_ACTIVITY_DEFAULT_RETENTION_METRICS=30           # Metrics requests: 30 days
AGENT_ACTIVITY_DEFAULT_RETENTION_AGENT_CARD=30        # Agent card requests: 30 days
AGENT_ACTIVITY_DEFAULT_RETENTION_LIFECYCLE=365        # Agent lifecycle: 1 year
AGENT_ACTIVITY_DEFAULT_RETENTION_VALIDATION=90        # Validations: 90 days
AGENT_ACTIVITY_DEFAULT_RETENTION_UNKNOWN=30           # Unknown types: 30 days

Internal System Monitoring (For SaaS Operators Only)¶

These are NOT for end users - they're for monitoring the platform itself.

INTERNAL_MONITORING_WEBHOOK_URL=          # Internal webhook for system alerts
INTERNAL_DATADOG_API_KEY=                 # Internal Datadog integration

🎛 Feature Flag Behavior¶

When `AGENT_ACTIVITY_LOGGING_ENABLED=false` (Default)¶

✅ No overhead - Activity logging code is completely skipped
✅ No database writes - No performance impact on your application
✅ Endpoints disabled - Activity query endpoints return 404
✅ Backward compatible - Existing agent authentication works normally

When `AGENT_ACTIVITY_LOGGING_ENABLED=true`¶

✅ Async logging - Non-blocking activity recording with < 50ms overhead
✅ Batch processing - Logs queued in Redis and flushed in batches (100 logs every 5 seconds)
✅ Automatic redaction - Sensitive data (passwords, tokens, secrets) automatically redacted
✅ Partitioned storage - Monthly database partitions for efficient queries and retention
✅ Query APIs enabled - Full REST API for querying, metrics, and exports

When `AGENT_ACTIVITY_LOG_BODIES=true`¶

⚠️ Storage impact - Request/response bodies are stored (subject to size limits)
✅ Complete debugging - Full request/response context for troubleshooting
✅ Size limits enforced - Bodies truncated at 10KB (requests) / 100KB (responses)
✅ Automatic sanitization - Sensitive parameters redacted before storage
💡 Recommendation - Enable only for debugging or compliance requirements

🔒 Security & Privacy¶

Automatic Redaction - Passwords, tokens, secrets automatically removed from logs
PII Protection - Optional email and phone masking
Access Control - Agents see only their own logs; users see their owned agents' logs
Size Limits - Request bodies capped at 10KB, response bodies at 100KB
Excluded Paths - Internal endpoints (/health, /metrics) not logged

📈 Activity Types¶

The system tracks these activity types with custom retention policies:

Activity Type	Description	Default Retention
`authentication`	OAuth token generation, login, refresh	365 days
`introspection`	Token validation and introspection	90 days
`a2a_rpc`	Agent-to-Agent RPC calls	30 days
`metrics`	Metrics and analytics requests	30 days
`agent_card`	Agent card requests	30 days
`lifecycle`	Agent creation, deletion, updates	365 days
`validation`	Token and request validation	90 days
`unknown`	Unclassified activities	30 days

🔗 Per-User Configuration & Integrations¶

Users can configure their own retention policies and integrations via API:

Configure Retention Policies¶

# Update retention for specific activity types
curl -X PUT "http://localhost:3000/oauth/user/activity/config/retention" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "authentication": 730,
    "introspection": 180,
    "a2a_rpc": 60
  }'

Configure S3 Archiving¶

# Enable per-user S3 archiving before deletion
curl -X PUT "http://localhost:3000/oauth/user/activity/config/archive" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "archive_enabled": true,
    "archive_s3_bucket": "my-activity-logs",
    "archive_s3_region": "us-east-1",
    "aws_access_key_id": "YOUR_AWS_KEY",
    "aws_secret_access_key": "YOUR_AWS_SECRET"
  }'

Configure Webhooks¶

# Add webhook integration for real-time notifications
curl -X POST "http://localhost:3000/oauth/user/integrations" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_type": "webhook",
    "name": "My Monitoring Webhook",
    "webhook_url": "https://your-app.com/webhooks/agent-activity",
    "webhook_secret": "your_webhook_secret",
    "webhook_events": ["authentication", "introspection", "error"]
  }'

Configure Datadog Integration¶

# Add Datadog integration for metrics
curl -X POST "http://localhost:3000/oauth/user/integrations" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_type": "datadog",
    "name": "My Datadog Metrics",
    "datadog_api_key": "YOUR_DATADOG_API_KEY",
    "datadog_app_key": "YOUR_DATADOG_APP_KEY",
    "datadog_site": "datadoghq.com"
  }'

Complete Documentation¶

For detailed documentation on Agent Activity Monitoring, see:

Agent Activity Monitoring Spec - Complete specification
Quick Start Guide - Usage examples
Multi-Tenant Configuration - Per-user settings
Retention & Cleanup - Data lifecycle

🎯 Use Cases¶

Debugging Agent Issues - See complete request/response history with full context
Compliance & Auditing - Generate audit reports for authentication and access events
Performance Monitoring - Track response times and identify slow endpoints
Usage Analytics - Understand how agents are using your service
Security Monitoring - Detect suspicious patterns and failed authentication attempts
Billing & Metering - Track API usage per agent for billing purposes

Performance Impact¶

< 50ms overhead - Async logging with minimal impact on request handling
< 100ms per batch - Efficient bulk inserts every 5 seconds
< 500ms queries - Fast filtered queries with partitioned storage
Scalable - Handles 1000+ concurrent log writes and 100K+ activity logs

Key Features¶

Authentication Methods¶

✅ OAuth 2.0 - Standard password-based authentication with refresh tokens
✅ Two-Factor Authentication (2FA/OTP) - TOTP-based second factor authentication using authenticator apps
✅ GitHub OAuth - Complete 2-step social login integration
✅ Google OAuth - Social login with Google integration
✅ Agent-to-Agent (A2A) - Machine-to-machine client credentials flow
✅ Agent Secret Tokens - AES-256-GCM cryptographically secure agent authentication
✅ P2P Identity Certification - Bind Ed25519 keypairs to Sentinel accounts for Stargate network

P2P Identity Certification (v0.2.0)¶

Stargate agents can bind their P2P identity to a Sentinel account, enabling Zero-Trust verification across the network.

Endpoint¶

POST /a2a/p2p/certify

Request¶

curl -X POST "https://api.traylinx.com/a2a/p2p/certify" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "peer_id": "12D3KooWAbCdEf...",
    "public_key": "base64-encoded-ed25519-public-key"
  }'

Response¶

{
  "certificate": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2026-01-26T00:00:00Z",
  "peer_id": "12D3KooWAbCdEf..."
}

Key Features¶

First-claim semantics — A peer_id can only be bound to one account
JWT certificates — Signed certificates for offline verification
1-year validity — Certificates expire after one year

CLI Integration¶

# Generate keypair and certify
tx stargate identity --generate
tx stargate certify

Advanced Security Features¶

✅ Token Type Segregation - Strict separation of user and agent token contexts
✅ Cryptographic Token Validation - AES-256-GCM encrypted agent tokens with PBKDF2
✅ Rate Limiting - 100 req/hour per agent with sliding window protection
✅ Comprehensive Audit Logging - Structured security event logging with monitoring
✅ Replay Protection - Timestamp-based validation with 1-hour validity window
✅ Secure Error Handling - OAuth 2.0 compliant errors with no sensitive data exposure
✅ Agent Introspection - Secure token validation endpoint for agent-to-agent verification

User Management¶

✅ User Registration - Account creation with email/phone verification
✅ Password Management - Secure password reset and change workflows
✅ Profile Management - User profile and preferences
✅ Social Account Linking - GitHub and Google account integration

🏛 Architecture¶

Core Components¶

CustomTokensController - Enhanced token generation with agent secret tokens
AgentIntrospectionController - Secure token validation endpoint
AgentSecretTokenService - Cryptographic token operations
TokenTypeValidation - Middleware for token segregation
Security Services - Audit logging, rate limiting, and monitoring

Security Architecture¶

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Agent A       │    │  Auth Service    │    │   Agent B       │
│                 │    │                  │    │                 │
│ 1. Authenticate │───▶│ 2. Generate      │    │                 │
│                 │    │    - access_token│    │                 │
│                 │    │    - agent_secret│    │                 │
│                 │◀───│      _token      │    │                 │
│                 │    │                  │    │                 │
│ 3. Send Request │────┼──────────────────┼───▶│ 4. Validate     │
│    with tokens  │    │                  │    │    Token        │
│                 │    │                  │    │                 │
│                 │    │ 5. Introspection │◀───│                 │
│                 │    │    Endpoint      │    │                 │
│                 │    │                  │───▶│ 6. Process      │
│                 │◀───┼──────────────────┼────│    Request      │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Performance & Monitoring¶

Key Metrics¶

Authentication success rate
Token generation latency
Active agent count
Failed authentication attempts
Rate limit violations

Health Check¶

curl https://api.makakoo.com/ma-authentication-ms/v1/api/health

Deployment¶

Production Deployment¶

GitHub auto-deploy configured
Docker-based deployment
Environment-specific configurations
Health monitoring and alerting

Staging Environment¶

Full feature testing
Performance validation
Security testing
Integration testing

Complete Documentation Index (20+ Files)¶

🎯 Getting Started¶

Main Documentation Hub - Complete navigation, quick start, and overview
Integration Examples - Ready-to-use code for JavaScript, React, Vue, Angular, Ruby, Node.js, Python, Flutter, React Native
Manual Testing Guide - Step-by-step localhost testing instructions
Localhost Credentials - Pre-configured test credentials and scenarios

API Documentation¶

Complete API Reference - All endpoints, parameters, responses, and examples
GitHub Authentication API - Comprehensive 2-step GitHub OAuth integration guide
A2A Authentication Specification - Agent-to-Agent authentication implementation details
Agent Secret Token API - Cryptographically secure agent authentication feature
Agent Introspection API - Secure token validation endpoint documentation

Technical Reference¶

Error Handling Guide - Comprehensive error codes, responses, and handling strategies
Token Type Validation - Token segregation implementation and usage
Security Implementation Guide - Complete security architecture and best practices
Agent Token Security Configuration - Configuration options and environment variables

Agent Activity Monitoring¶

Agent Activity Monitoring Overview - Complete feature specification and architecture
Quick Start Guide - Get started with activity monitoring
Multi-Tenant Configuration - Per-user settings and integrations
Retention & Cleanup - Data lifecycle management

Troubleshooting & Support¶

Comprehensive Troubleshooting Guide - Complete diagnostic procedures and solutions
A2A Basic Troubleshooting - Common A2A authentication issues and fixes

🧪 Testing & Tools¶

Postman Collection - 6000+ lines of comprehensive API tests
Postman Environment - Pre-configured localhost testing environment

Support & Getting Help¶

Quick Start Path¶

📖 Start Here: Main Documentation Hub - Complete navigation and quick start guide
🔧 API Reference: Complete API Reference - All endpoints with examples
🧪 Test Your Setup: Postman Collection - Import and start testing immediately
🛠️ Common Issues: Troubleshooting Guide - Diagnostic procedures and solutions

📞 Support Escalation¶

Step 1: Check application logs for detailed error messages
Step 2: Use health check endpoint: GET /health
Step 3: Review relevant troubleshooting documentation
Step 4: Contact development team with specific error details and request examples

Documentation Quality¶

✅ 20+ comprehensive documentation files
✅ 100% API endpoint coverage
✅ Multi-platform integration examples
✅ Complete security implementation guide
✅ Agent Activity Monitoring with SaaS multi-tenancy
✅ Extensive troubleshooting documentation
✅ 6000+ lines of Postman test scenarios

🏷 Version & Compatibility¶

Current Version: 1.1.0
Last Updated: November 4, 2025
Ruby Version: 3.0.0
Rails Version: 6.1.x
Documentation Files: 20+
API Endpoints Documented: 100%
Test Success Rate: 98.53%
Code Coverage: 94.59%

🎯 What Makes This Service Special¶

🔒 Advanced Security: AES-256-GCM encrypted agent tokens with cryptographic binding
📊 Activity Monitoring: Complete SaaS multi-tenant activity logging with webhooks and integrations
📖 Exceptional Documentation: 20+ comprehensive files covering every aspect
🧪 Complete Testing Suite: 6000+ lines of Postman tests with localhost environment
🚀 Production Ready: Used in production with comprehensive monitoring and alerting
🛠️ Developer Friendly: Multiple platform examples and extensive troubleshooting guides

For the complete documentation experience, start with the Main Documentation Hub which provides guided navigation through all 20+ documentation files.

Authentication Service¶

Quick Start¶

Choose Your Authentication Method¶

Complete Documentation (17 Files)¶

Development Setup¶

Using Docker (Recommended)¶

Native Setup¶

🧪 Testing¶

Run Tests¶

API Testing¶

Configuration¶

Company Branding Configuration¶

Environment Variables¶

🔒 Two-Factor Authentication (2FA/OTP)¶

🔑 How OTP Authentication Works¶

📱 User Database Schema¶

Authentication Logic Flow¶

Error Handling¶

Implementation Features¶

Managing User 2FA Status¶

📱 Authenticator App Setup¶

Agent Activity Monitoring¶

🎯 What is Agent Activity Monitoring?¶

Quick Start¶

1. Enable Agent Activity Monitoring¶

2. Run Database Migrations¶

3. Query Your Agent's Activities¶

Available Endpoints¶

Configuration Reference¶

Core Settings¶

Per-User Configuration API¶

System Default Retention Policies¶

Internal System Monitoring (For SaaS Operators Only)¶

🎛 Feature Flag Behavior¶

When AGENT_ACTIVITY_LOGGING_ENABLED=false (Default)¶

When AGENT_ACTIVITY_LOGGING_ENABLED=true¶

When AGENT_ACTIVITY_LOG_BODIES=true¶

🔒 Security & Privacy¶

📈 Activity Types¶

🔗 Per-User Configuration & Integrations¶

Configure Retention Policies¶

Configure S3 Archiving¶

Configure Webhooks¶

Configure Datadog Integration¶

Complete Documentation¶

🎯 Use Cases¶

Performance Impact¶

Key Features¶

Authentication Methods¶

P2P Identity Certification (v0.2.0)¶

Endpoint¶

Request¶

Response¶

Key Features¶

CLI Integration¶

Advanced Security Features¶

User Management¶

🏛 Architecture¶

Core Components¶

Security Architecture¶

Performance & Monitoring¶

Key Metrics¶

Health Check¶

Deployment¶

Production Deployment¶

Staging Environment¶

Complete Documentation Index (20+ Files)¶

🎯 Getting Started¶

API Documentation¶

Technical Reference¶

Agent Activity Monitoring¶

Troubleshooting & Support¶

🧪 Testing & Tools¶

Support & Getting Help¶

Quick Start Path¶

📞 Support Escalation¶

Documentation Quality¶

🏷 Version & Compatibility¶

🎯 What Makes This Service Special¶

When `AGENT_ACTIVITY_LOGGING_ENABLED=false` (Default)¶

When `AGENT_ACTIVITY_LOGGING_ENABLED=true`¶

When `AGENT_ACTIVITY_LOG_BODIES=true`¶