Skip to content

The Epic Suite

Add a tool to the suite

A tool of your own joins an organisation's suite menu by publishing a manifest at /.well-known/epic-tool.json on its own domain. An owner or admin adds it after seeing what it asks for; it stays on its own domain, its people sign in with Epic Context, and its actions arrive signed.

The suite is open for tools that someone else built: an internal dashboard, a niche app, a service your team relies on. Such a tool does not need Epic Context's code or a shared secret. It describes itself in one JSON file.

The manifest

Publish it at https://<your-tool>/.well-known/epic-tool.json:

{
  "id": "acme-reviews",
  "name": "Reviews",
  "description": "Customer reviews, collected per product.",
  "app_name": "Acme Reviews",
  "icon": "MessageSquareQuote",
  "current": "https://reviews.acme.example/",
  "for_ai": "Customer reviews per product. Read them before writing customer insights; ask for a new import with call_tool_action.",
  "actions": [
    { "name": "import_reviews", "description": "Import the latest reviews for a product." }
  ],
  "actions_url": "https://reviews.acme.example/epic/actions",
  "notifications": [
    { "id": "import_failed", "label": "An import failed", "to": "who started it" }
  ]
}
FieldRequiredWhat it is
idyesLowercase letters, digits and hyphens. May not be the id of a built-in tool
nameyesThe label in the menu, at most 40 characters
descriptionyesOne line, at most 240 characters
app_nameyesThe app behind it, shown on the consent screen (at most 60)
iconyesA Lucide icon name for the menu
currentyesWhere the tool opens: an https address on the same origin as the manifest
for_ainoOne sentence for an AI: when work goes here, and with which verb (at most 300)
actionsnoActions AI sessions may call, each with a name and a description
actions_urlwith actionsWhere Epic Context posts an action; https, same origin as the manifest
events, notifications, widgets, settings, settings_pages, theme, countnoWhat it emits, the notifications it sends, dashboard cards, settings it reads, its pages in the settings menu, its colour and the number on its icon

What is checked

  • The manifest is fetched over https only, without following redirects, with a five-second timeout and a 64 KB limit. Private addresses and .local or .internal hosts are refused.
  • current and actions_url must be on the manifest's own origin.
  • A tool that declares actions must give an actions_url.

Adding it

An owner or admin opens Settings › Organisation › Apps, enters the tool's address under Add your own app, and sees a consent screen first: where it opens, that people sign in there with their Epic Context account, which actions AI sessions may call, what it wants to hear about and which widgets it offers. On confirm the tool joins the menu, at the end, and Epic Context shows a signing secret once. Removing the tool takes it out of the menu and stops every action at once.

Signing people in

Your tool signs people in with their Epic Context account over OpenID Connect. Discovery is at https://www.epiccontext.com/.well-known/openid-configuration; register your client with dynamic client registration (/oauth/register) and request the openid scope. The ID token tells you who the person is.

Receiving an action

When an AI session calls one of your actions with call_tool_action, Epic Context posts JSON to your actions_url:

{
  "action": "import_reviews",
  "args": { "product": "…" },
  "reason": "The persona needs the latest review themes.",
  "organization": { "id": "…", "slug": "…", "name": "…" },
  "user": { "id": "…", "email": "…", "name": "…" },
  "role": "member"
}

The request carries X-Epic-Signature: t=<unix seconds>,v1=<signature>, where the signature is the hex HMAC-SHA256 of <t>.<raw body>, keyed with the signing secret exactly as it was shown. Reject a signature older than five minutes. Answer with JSON within fifteen seconds; your answer goes back to the AI session.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyEpicSignature(secret: string, rawBody: string, header: string): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=") as [string, string]));
  const t = Number(parts.t);
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > 300 || !parts.v1) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return expected.length === parts.v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Next

Last updated: