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.
tRPC is internal
/<plugin>/trpc exists on every service for service-to-service calls. It is not a supported external API; integrate over GraphQL or webhooks at the gateway.
