# API & Integrations

Authenticate, query the federated GraphQL API, and connect external systems


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](https://github.com/erxes/erxes/blob/f91e8c6f4714c910a32c6b6e14fe085f6435c89e/backend/gateway/src/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](https://github.com/erxes/erxes/blob/f91e8c6f4714c910a32c6b6e14fe085f6435c89e/backend/gateway/src/middlewares/userMiddleware.ts) is what turns your credential into the context the subgraphs trust. See [Backend & API Gateway](https://erxes.io/docs/architecture-backend-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](https://github.com/erxes/erxes/blob/f91e8c6f4714c910a32c6b6e14fe085f6435c89e/backend/core-api/src/modules/apps/graphql/schemas.ts) 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](https://erxes.io/docs/api-authentication). For a public website or portal frontend, use the portal token with `cp*` operations; see [Client Portal](https://erxes.io/docs/app-client-portal).

> [!WARNING]
> **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.

## Guides

- [Authentication & Permissions](https://erxes.io/docs/api-authentication): Team, portal, app, and agent credentials
- [GraphQL API](https://erxes.io/docs/api-graphql): Federated endpoint and pagination
- [Integration Development](https://erxes.io/docs/api-integration-development): External systems via GraphQL, tRPC, and webhooks