Authentication & Permissions

Authenticate team members, portals, apps, and agents at the gateway. This guide follows version 3.1.7 (03acdf712c).

For the user model, see Organizations, Users & Permissions.

Credential families

backend/gateway/src/middlewares/userMiddleware.ts:

• Team member: Authorization: Bearer <token> or auth-token cookie JWT, verified against models.Users plus redis.get(user_token_<id>_<token>). Issued by Core API login (backend/core-api/src/modules/auth/); persisted with a 24h Redis TTL via saveValidatedToken.
• Client Portal: x-app-token JWT (JWT_TOKEN_SECRET) resolving to models.ClientPortals (req.clientPortal). A separate client-auth-token header or cookie identifies a signed-in portal user (req.cpUser).
• App: erxes-app-token resolving to an active models.Apps record; the gateway synthesizes req.user = { _id: 'app:<id>' } as a machine principal.
• Website check: erxes-core-token plus erxes-core-website-url verified against erxes.io/check-website for limited script flows.

Tenant selection uses getSubdomain(req) (backend/erxes-api-shared/src/utils/utils.ts): the leftmost label of the forwarded or request hostname. Backend models are generated per subdomain.

Permissions

Team-member authorization uses the permissions module (backend/core-api/src/modules/permissions/, shared utils in backend/erxes-api-shared/src/core-modules/permissions/). Plugins declare meta/permissions.ts; tRPC agent tools reference those actions. Portal operations (cp*) derive the portal from context and still enforce their own filters; the prefix alone does not imply published-only or read-only behavior.

Verify

1. Sign in, capture the token, and call /graphql with Bearer, then with a missing token to confirm rejection.
2. Call a portal operation with x-app-token and confirm another portal's data is not visible.
3. Rotate JWT_TOKEN_SECRET in staging and confirm old tokens fail.

Source references

• Gateway middleware.
• Subdomain helper.