README.md

May 6, 2026 · View on GitHub

Evo CRM Auth Service

Authentication, RBAC, OAuth 2.0 and token issuance service for the Evo CRM Community.

Website · Documentation · Community · Support

About

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.

Part of the Evo CRM Community

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.git

The 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.

Features

Authentication

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)

Authorization

Role-Based Access Control (RBAC): account_owner and agent
Token rotation and secure session management

Compliance

LGPD-compliant data privacy controls
Comprehensive audit logging for all user actions
Database-driven feature flags

API

RESTful API with documented endpoints
OpenAPI / Swagger documentation
Webhook support for real-time notifications
Multi-language support (EN, PT-BR)

Quick Start

Prerequisites

Ruby 3.4.4
Rails 7.1+
PostgreSQL 12+
Redis 6+

Installation

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 3001

The service will be available at http://localhost:3001.

Default credentials: configured in db/seeds.rb. Review and change them before any deployment.

API documentation

Once running, Swagger UI is available at:

http://localhost:3001/api-docs

Configuration

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_password

See .env.example for all available variables.

Authentication examples

Bearer token (recommended)

# 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"

API access token (server-to-server)

curl -X GET http://localhost:3001/api/v1/users \
  -H "api_access_token: YOUR_API_TOKEN"

OAuth 2.0 Bearer token (third-party apps)

curl -X GET http://localhost:3001/api/v1/users \
  -H "Authorization: Bearer YOUR_OAUTH_TOKEN"

Architecture

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.

Key Endpoints

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

Testing

# All tests
bundle exec rspec

# Specific file
bundle exec rspec spec/models/user_spec.rb

# With coverage
COVERAGE=true bundle exec rspec

Documentation

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

DeviseTokenAuth — JWT authentication
Doorkeeper — OAuth 2.0 provider
ROTP — TOTP implementation
RSwag — API documentation

License

Evo CRM Auth Service is licensed under the Apache License 2.0. See LICENSE for details.

Trademarks

"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.