API & Integrations

Call erxes from outside the platform: one federated GraphQL endpoint, a small set of credential types, and webhooks for event-driven integration.

The endpoint

All API traffic goes through the gateway on port 4000: POST /graphql directly, or https://<domain>/gateway/graphql behind the reverse proxy from the deployment template. An Apollo Router inside the gateway (apollo-router/index.ts) composes the core subgraph plus one subgraph per enabled plugin API, so a single request can span modules and every plugin's operations share the endpoint. Subscriptions run over WebSocket on the same /graphql path, and plugin HTTP routes (webhooks, provider callbacks) are reachable through the gateway's /pl:<name> proxy.

Never call a subgraph port directly: the gateway's userMiddleware is what turns your credential into the context the subgraphs trust. See Backend & API Gateway for composition and proxying.

Credential types

The gateway checks every credential before routing, then forwards the result to subgraphs as user, clientportal, and cpuser headers. The common cases:

Credential	Transport	Issued by	Identifies
Team-member JWT	Authorization: Bearer or auth-token cookie	login mutation or WorkOS SSO; 1-day expiry, registered in Redis	A Users document
Client Portal token	x-app-token header	clientPortalAdd / clientPortalChangeToken; JWT carrying clientPortalId	A ClientPortals record; scopes cp* operations
App token	erxes-app-token header (x-app-api-token doubles as a CORS bypass)	appsAdd mutation (requires appsManage)	Machine principal app:<id>; owner when allowAllPermission

Issuance, rotation, and edge cases (expired tokens, dual headers, WebSocket auth) are in Authentication & Permissions. For a public website or portal frontend, use the portal token with cp* operations; see Client Portal.

Guides

• Authentication & PermissionsTeam, portal, app, and agent credentials
• GraphQL APIFederated endpoint and pagination
• Integration DevelopmentExternal systems via GraphQL, tRPC, and webhooks