HXP Authentication and Access
Organization API keys for M2M, operator sessions, delegated MCP tokens, and provider signatures
HXP uses different authentication for its operator UI, delegated assistants, and provider callbacks. A credential for one surface does not grant access to the others.
Organization API keys for third-party systems
The new M2M surface is https://v3.hxp.journey.com/api/external/v1/messaging. See the API keys and M2M guide for activation status, key creation and exact examples.
Send Authorization: Bearer <organization-api-key>. WorkOS determines the key's organization and permissions; HXP also requires its active grant, expiration, exact workspace and audience. Keys created through Settings → Developer API → Messaging integrations receive this grant. Existing widget-created keys do not automatically gain messaging access. The secret is displayed once; keep it server-side.
This is API-key authentication for unattended systems, not an OAuth client-credentials token exchange. No token endpoint is needed. The key does not authenticate /api/v1/orgs/... operator routes or /api/operator-mcp.
Operator HTTP APIs
/api/v1/orgs/{orgId}/messaging and /api/v1/orgs/{orgId}/collaboration resolve the operator through HXP's WorkOS AuthKit session. They do not parse Journey API keys or MCP bearer tokens.
- The operator signs in to HXP and selects an authorized organization.
- Each request supplies an explicit
scopequery parameter identifying an accessible organization, brand, or venue workspace. - HXP resolves the session actor, organization membership, permission, resource grants, guest access, and audience on the server.
- Mutating requests enforce same-origin request checks and command-specific authorization.
| Operation | Current HXP permission |
|---|---|
| Read messaging, Actions, or collaboration state | hxp:guests:read |
| Post comments; create, claim, finish, cancel, or hand off Actions | Also hxp:organizations:manage |
| Read/snooze personal attention, react, or ask privately | Read access plus command-specific checks |
| Publish an AI answer into the thread | Write access |
A team audience additionally requires team membership. Membership alone does not grant access to an otherwise unauthorized guest or venue. Scope IDs and guest IDs are selectors, never authorization.
These routes are an internal operator contract. The examples in this section describe HXP's own client and must not be used to build a third-party service around exported session cookies. There is no supported client-credentials or API-key exchange for these routes today.
Delegated operator MCP
When activated, /api/operator-mcp?organizationId={orgId}&scopeId={scopeId} accepts an audience-bound WorkOS OAuth bearer token for a registered assistant host. This is delegated operator access, not an unattended service account.
Discover the configured resource and authorization server at:
GET /.well-known/oauth-protected-resource
Host: v3.hxp.journey.comDiscovery returns resource, authorization_servers, scopes_supported, and bearer_methods_supported. A 503 means this adapter is not configured; it is not a token-acquisition endpoint.
The adapter verifies the signature using the configured issuer's /oauth2/jwks, with RS256, the exact issuer and resource audience, and the following claims:
| Claim | Requirement |
|---|---|
sub | The operator's WorkOS user ID |
exp, iat | Required token timestamps; expiration is verified |
org_id | Exact WorkOS organization ID mapped to the requested HXP organization |
client_id | A Journey-registered, allowlisted assistant host |
scope | Space-separated required HXP collaboration scopes |
aud | Configured MCP resource URL; not a Core API audience |
iss | Configured authorization server |
hxp:collaboration:read is required for every MCP request. start_task and cancel_task additionally require hxp:collaboration:write; request both scopes for a writing host. Both the host allowlist and the token must allow the operation. These OAuth scopes do not replace the operator's HXP permissions.
HXP re-resolves current active WorkOS membership, role permissions, and workspace grants. Tool arguments must match the request URL's organizationId and scopeId. The token is never forwarded to Core. If an HTTP Origin header is supplied, it must match the configured resource origin.
Journey must first qualify and register the host, configure the issuer/resource and permitted client scopes, and verify the operator's consent and scoped access in the target deployment. The HXP repository implements resource-server validation; it does not supply a self-service OAuth client registration or a general token-issuance API. Use the authorization server's actual provisioned flow; do not manufacture tokens or assume a grant type.
Provider ingress
Slack requests use the configured installation's signing secret, signature, and timestamp against the raw request body. SMS delivery callbacks use provider signature verification and exact installation/delivery matching. These signatures authenticate the provider; they are not credentials for arbitrary third-party clients. External Slack identities must be linked to an HXP operator before a bounded consultation can be started.
Credentials that are not interchangeable
The Journey API keys and Core authentication guides describe other API surfaces. Neither Core jny_ keys nor arbitrary WorkOS JWTs authenticate the HXP machine messaging endpoint. The brands endpoint remains /api/external/v1/brands; it requires its own permission. Messaging permissions do not implicitly authorize brands or other Journey APIs.
See Operator MCP for the supported tool list and Threads and listening for the operator event feed, or M2M for third-party polling.