Authentication

Create named API keys in Settings > Connections > API keys. Select only the scopes required by the integration. The raw key is displayed once, so store it in a secret manager when it is created.

Use the key as a bearer token:

curl https://portal.heyx.app/public-api/publicapi.v1.Workspace/Me \
  -H "Authorization: Bearer <your-workspace-api-key>" \
  -H "Content-Type: application/json" \
  -d '{}'

You can also send X-API-Key, but Authorization: Bearer is preferred.

Scopes

Scopes have the same exact meaning for public Connect endpoints and Workspace MCP tools. Operations that list more than one scope require all of them.

Scope	Operations
`me:read`	`Me`
`portfolio:read`	`GetPortfolio`
`portfolio:create`	`CreatePortfolio`
`portfolio_datafield:write`	`PatchPortfolioDataFields`
`portfolio_file:create`	Create and complete document or photo uploads
`portfolio_file:read`	List and download-link document or photo records; also required when creating a comment with attachments
`portfolio_comment:create`	`CreatePortfolioComment`
`portfolio_event:create`	`CreatePortfolioEvent`
`datafield:read`	`ListDataFields`
`correspondence:create`	`AddCorrespondenceMessage`
`advanced_task:read`	`ListAdvancedTaskInstances`
`advanced_task:update`	`UpdateAdvancedTaskInstance`
`problem:read`	`ListProblems`
`problem:create`	`CreateProblem`
`problem:update`	`UpdateProblem`
`work_order:read`	`ListWorkOrders`
`work_order:create`	`CreateWorkOrder`
`work_order:update`	`UpdateWorkOrder`
`catalog:read`	`ListProducts`, `ListDiscounts`
`quote:read`	`GetQuote`, `ListQuotes`
`quote:create`	`CreateQuote`
`quote:confirm`	`ConfirmQuote`
`order:read`	`GetOrder`, `ListOrders`
`payment:read`	`GetPayment`, `ListPayments`
`payment:create`	`CreatePayment`
`payment:update`	`RecordManualPayment`
`invoice:create`	`CreateInvoice`
`appointment:create`	`CreateAppointment`
`action_request:create`	`CreateManualActionRequest`
`member:read`	`ListMembers`
`member_roles:update`	`ReplaceMemberRoles`
`role:read`	`ListRoles`
`team:read`	`ListTeams`
`team:create`	`CreateTeam`
`member:invite`	`EmailMemberInvitation`
`member_invite_link:create`	`CreateInviteLink`

API keys are creator-bound. Requests use the creating account’s current workspace membership, resource authorization, and delegation rights in addition to the key scopes. A scope cannot grant access the creator does not have.

Create separate named keys for separate clients or duties so each can be expired, restricted, or revoked independently.

IP restrictions

API keys can be restricted to specific IP addresses or CIDR ranges. If a key has no allowed CIDRs, it can be used from any IP.

Timeouts

If HeyX cannot start processing a request within 30 seconds, it returns a retryable timeout response. If processing has already started but the HTTP request times out, the operation may still continue in the background. Never assume a timeout cancelled a mutation, and do not blindly retry non-idempotent operations.