# HXP Authentication and Access
> Source: /hxp/authentication
> 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 [#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](/hxp/machine-integrations) 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 [#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.

1. The operator signs in to HXP and selects an authorized organization.
2. Each request supplies an explicit `scope` query parameter identifying an accessible organization, brand, or venue workspace.
3. HXP resolves the session actor, organization membership, permission, resource grants, guest access, and audience on the server.
4. 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.

<Warning>
  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.
</Warning>

## Delegated operator MCP [#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:

```http
GET /.well-known/oauth-protected-resource
Host: v3.hxp.journey.com
```

Discovery 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 [#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 [#credentials-that-are-not-interchangeable]

The [Journey API keys](/api-reference/authentication/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](/hxp/operator-mcp) for the supported tool list and [Threads and listening](/hxp/threads-and-events) for the operator event feed, or [M2M](/hxp/machine-integrations) for third-party polling.