Your requests, in your tools.

Create a key in the portal

1. Sign in to your ordinary support portal using an enabled sign-in method.
2. Open API keys beside My requests (in the navigation menu on the chat layout).
3. Choose Create API key, enter a name, select permissions and a lifetime of 1–30 days.
4. Copy the key once into your server's secret store. The full key cannot be retrieved later.

The key acts as the signed-in company administrator. It stops working if that administrator loses company access, moves company, or its sign-in configuration changes. An administrator can inspect and revoke the company's keys. Ordinary company users cannot create keys.

Keys issued through the existing embedded panel can act as a selected company member; member keys see only that member's own requests. They also depend on the signed membership and embedded-support settings. Keys cannot create other keys.

For staff entering the customer portal from the workspace, keys retain that sign-in's staff-session binding. Use a direct customer sign-in for an integration that must outlive a staff sign-out.

Authentication and permissions

Use the exact portal origin where you created the key, including a custom domain when applicable. Do not switch between the custom domain and the Escalio subdomain. Send Authorization: Bearer <customer key>. Browser cookies and organization keys are not substitutes.

• read: list and read accessible requests.
• create: create a public request as the key's customer account.
• reply: reply publicly to an accessible request.

Company admins can use the company view; ordinary member keys are limited to their own requests. Scopes restrict access further. Internal notes, other companies, staff Settings and arbitrary requester impersonation are unavailable.

Set ESCALIO_PORTAL to the portal origin without a trailing slash, ESCALIO_CUSTOMER_KEY from your secret store, and ESCALIO_TICKET_ID to a returned ticket UUID. For each new write, persist a unique ESCALIO_REQUEST_ID and its exact payload. The cURL examples use a POSIX shell; Python uses the standard library.

Methods and examples

Download the OpenAPI 3.1 reference. All responses are JSON. Unknown JSON body fields are rejected. Subject: 1–240 characters, no control characters. Body: 1–20,000 characters, not blank. Format: markdown (default) or plain. Markdown can include code blocks for logs; file upload is not part of this API.

curl --fail-with-body --silent --show-error --request GET \
  "$ESCALIO_PORTAL/api/portal/customer/v1/me" \
  --header "Authorization: Bearer $ESCALIO_CUSTOMER_KEY"

curl --fail-with-body --silent --show-error --request GET \
  "$ESCALIO_PORTAL/api/portal/customer/v1/tickets" \
  --header "Authorization: Bearer $ESCALIO_CUSTOMER_KEY"

{
  "subject": "API connection issue",
  "body": "## What happened\nThe nightly job returned an error.\n\n```text\nrequest_id: demo-42\nstatus: 503\n```",
  "format": "markdown"
}

curl --fail-with-body --silent --show-error --request POST \
  "$ESCALIO_PORTAL/api/portal/customer/v1/tickets" \
  --header "Authorization: Bearer $ESCALIO_CUSTOMER_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $ESCALIO_REQUEST_ID" \
  --data-binary @ticket.json

import json, os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

payload = open("ticket.json", "rb").read()
request = Request(os.environ["ESCALIO_PORTAL"].rstrip("/") + "/api/portal/customer/v1/tickets",
    method="POST", data=payload, headers={
        "Authorization": "Bearer " + os.environ["ESCALIO_CUSTOMER_KEY"],
        "Content-Type": "application/json",
        "Idempotency-Key": os.environ["ESCALIO_REQUEST_ID"],
    })
try:
    with urlopen(request, timeout=30) as response:
        print(json.loads(response.read()))
except HTTPError as error:
    raise SystemExit(f"HTTP {error.code}: {error.read().decode()}")

curl --fail-with-body --silent --show-error --request GET \
  "$ESCALIO_PORTAL/api/portal/customer/v1/tickets/$ESCALIO_TICKET_ID" \
  --header "Authorization: Bearer $ESCALIO_CUSTOMER_KEY"

{
  "body": "The issue is resolved, thank you.",
  "format": "plain"
}

curl --fail-with-body --silent --show-error --request POST \
  "$ESCALIO_PORTAL/api/portal/customer/v1/tickets/$ESCALIO_TICKET_ID/messages" \
  --header "Authorization: Bearer $ESCALIO_CUSTOMER_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $ESCALIO_REQUEST_ID" \
  --data-binary @reply.json

curl --fail-with-body --silent --show-error --request POST \
  "$ESCALIO_PORTAL/api/portal/customer/v1/logout" \
  --header "Authorization: Bearer $ESCALIO_CUSTOMER_KEY"

Retry safely

Ticket creation and replies require Idempotency-Key, 8–100 characters. Reuse it only for the same operation, ticket and payload. After a timeout, retry with backoff and the same key: the message may already have been saved. Both first success and identical retries return 201 with {"id": "ticket UUID"}.

Receipts are shared across keys for the same customer account in the same support organization and guaranteed for seven days. A new customer account has a different retry scope. Different operations or payloads under the same key return 409. Do not bypass a conflict with a new ID. A reply to a closed request may return a new follow-up ID; save the returned ID before continuing.

Errors and limits

Up to 20 active keys per company, expiring in 1–30 days. Up to 120 successful API operations per key per minute. Lists contain 50 tickets per page; conversations contain 100 public messages per page. Revoked/expired keys remain in the portal's recent history.

Errors include code, detail and request_id. Save the request ID for troubleshooting. Never log the key. If your support portal requires acceptance of terms, sign in and accept them before retrying a blocked write.

Customer MCP

Configure a Streamable HTTP MCP client with the same customer key as a Bearer token and the endpoint https://YOUR-PORTAL/api/portal/customer/mcp. Customer MCP does not use the staff OAuth connection.

Available tools: list_requests, get_request, create_request and reply_to_request. The key's scopes determine which tools are offered. Write tools use request_key in their arguments instead of the REST idempotency header. Replies are public; review the content before sending.