Security & Access Control

Security is essential when working with AI-powered tools that access sensitive business data. Billx-Agent includes built-in mechanisms to help you maintain safe, controlled access to your API and databases.

---

✅ DO

✔️ Use Strong JWT Authentication

• All authenticated endpoints require a JWT token

• Tokens should be stored securely in your client app (never in local storage for web)

• Rotate tokens periodically if using long-lived sessions

---

✔️ Leverage Role-Based Access Control (RBAC)

Assign users one of three predefined roles:

Role	Access Scope
User	Query own database, view results
Admin	Manage users within their organization
Super Admin	System-wide management (roles, quotas)

Use POST /users/{user_id}/change-role/{new_role_id} to promote/demote users.

---

✔️ Use Read-Only DB Credentials in db_url

• The db_url you pass to Billx-Agent should point to a read-only database user

• Never use root or write-enabled credentials

postgresql://readonly_user:password@host:5432/mydb

---

✔️ Protect Redis & DB Instances

• Ensure Redis (used for token revocation) is firewalled or VPC-restricted

• PostgreSQL should also block public traffic unless access is needed for Billx-Agent

---

✔️ Log Out When Done

Calling GET /logout immediately invalidates the active token:

• Adds it to a Redis blocklist

• Prevents reuse, even if not yet expired

---

❌ AVOID

❌ Exposing API Tokens in Frontend Code

Tokens should be stored in:

• HTTP-only cookies (browser)

• Encrypted secrets (backend)

• Secure keychains (mobile)

Never hardcode tokens into frontend source files.

---

❌ Granting Super Admin Privileges to Everyone

• Super Admin role can create/delete roles, view all users, and access quotas.

• Use with caution — reserve for platform owners or internal ops teams.

---

❌ Sharing db_url Across Tenants

Each user/org should pass their own scoped db_url to isolate data access. Never use a shared database for multiple customers unless you're partitioning at the table level with enforced row-level security (RLS).

---

🛡️ Billx-Agent is built with security-first principles. Following these practices ensures safe use in production environments.