Authentication, RBAC, OAuth 2.0 and token issuance service for the Evo CRM Community.
Website · Documentation · Community · Support
Evo CRM Auth Service is the authentication and authorization microservice of the Evo CRM Community. Built on Ruby on Rails 7.1, it provides Bearer token authentication, OAuth 2.0 (Doorkeeper), Multi-Factor Authentication (TOTP, Email OTP, backup codes), Role-Based Access Control with simple account_owner / agent roles, and LGPD-compliant audit logging.
Evo CRM Auth Service is part of the Evo CRM Community ecosystem maintained by Evolution Foundation. To use the full stack, clone the umbrella repository with submodules:
git clone --recurse-submodules git@github.com:evolution-foundation/evo-crm-community.gitThe Community Edition is single-tenant by design — one account, no multi-tenancy overhead, no super-admin, no billing or plans. The role hierarchy is simple: account_owner and agent.
- Bearer token authentication with JWT
- OAuth 2.0 provider via Doorkeeper (RFC 6749)
- Multi-Factor Authentication (TOTP, Email OTP, backup codes)
- Legacy DeviseTokenAuth support for backward compatibility
- Well-Known discovery endpoints (RFC 8414)
- Role-Based Access Control (RBAC):
account_ownerandagent - Token rotation and secure session management
- LGPD-compliant data privacy controls
- Comprehensive audit logging for all user actions
- Database-driven feature flags
- RESTful API with documented endpoints
- OpenAPI / Swagger documentation
- Webhook support for real-time notifications
- Multi-language support (EN, PT-BR)
- Ruby 3.4.4
- Rails 7.1+
- PostgreSQL 12+
- Redis 6+
git clone git@github.com:evolution-foundation/evo-auth-service-community.git
cd evo-auth-service-community
# Install dependencies
bundle install
# Configure database
rails db:create
rails db:migrate
rails db:seed
# Start server
rails server -p 3001The service will be available at http://localhost:3001.
Default credentials: configured in
db/seeds.rb. Review and change them before any deployment.
Once running, Swagger UI is available at:
http://localhost:3001/api-docs
Create a .env file:
# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/evo_auth_service_development
# Redis
REDIS_URL=redis://localhost:6379/1
# JWT secret
DEVISE_JWT_SECRET_KEY=your_super_secret_jwt_key
# OAuth
DOORKEEPER_SECRET_KEY=your_doorkeeper_secret_key
# Frontend URL (CORS and OAuth callbacks)
FRONTEND_URL=http://localhost:3000
# Email (MFA and notifications)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=your_email@example.com
SMTP_PASSWORD=your_app_passwordSee .env.example for all available variables.
# Login
curl -X POST http://localhost:3001/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com", "password": "password"}'
# Use the token
curl -X GET http://localhost:3001/api/v1/auth/me \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"curl -X GET http://localhost:3001/api/v1/users \
-H "api_access_token: YOUR_API_TOKEN"curl -X GET http://localhost:3001/api/v1/users \
-H "Authorization: Bearer YOUR_OAUTH_TOKEN"The auth service issues tokens consumed by all other services in the Evo CRM Community ecosystem:
┌──────────────────────────┐
│ Evo CRM Auth Service │ ← (you are here)
│ (token issuance, RBAC) │
└────────────┬─────────────┘
│ Bearer token
┌──────────────────────┼──────────────────────┐
↓ ↓ ↓
evo-ai-crm-community evo-ai-core-service evo-ai-processor
(conversations, (agents, tools, (agent execution,
contacts) API keys, folders) sessions)
Inter-service communication uses Bearer token authentication. Tokens issued by this service are forwarded between services — no account-id header required.
| Endpoint | Description |
|---|---|
POST /api/v1/auth/login |
User authentication (Bearer token) |
GET /api/v1/auth/me |
Get current user info |
POST /auth/sign_in |
Legacy DeviseTokenAuth |
POST /api/v1/mfa/setup_totp |
Setup TOTP MFA |
GET /oauth/authorize |
OAuth 2.0 authorization |
POST /oauth/token |
OAuth 2.0 token exchange |
GET /.well-known/oauth-authorization-server |
OAuth server metadata |
# All tests
bundle exec rspec
# Specific file
bundle exec rspec spec/models/user_spec.rb
# With coverage
COVERAGE=true bundle exec rspec| Resource | Link |
|---|---|
| Website | evolutionfoundation.com.br |
| Documentation | docs.evolutionfoundation.com.br |
| Community | evolutionfoundation.com.br/community |
| Changelog | CHANGELOG.md |
| Contributing | CONTRIBUTING.md |
| Security | SECURITY.md |
Contributions are welcome! Please read CONTRIBUTING.md for guidelines on how to submit issues, propose features, and open pull requests.
Join our community to discuss ideas and collaborate.
For security issues, do not open a public issue. Email suporte@evofoundation.com.br or use GitHub's private vulnerability reporting. See SECURITY.md for details.
This service builds on excellent open-source software:
- DeviseTokenAuth — JWT authentication
- Doorkeeper — OAuth 2.0 provider
- ROTP — TOTP implementation
- RSwag — API documentation
Evo CRM Auth Service is licensed under the Apache License 2.0. See LICENSE for details.
"Evolution Foundation", "Evolution" and "Evo CRM Auth Service" are trademarks of Evolution Foundation. See TRADEMARKS.md for the brand assets policy.
Third-party attributions are documented in NOTICE.
Made by Evolution Foundation · © 2026