Custom Integrations

When the Ema Platform Integrations catalog doesn't already have what you need, a custom integration lets you wrap any external API and expose it to your AI Employees as Tools. A custom integration holds the authentication and connection details for one external system; the Tools inside it are the individual operations an AI Employee can invoke in that system.

This page walks the end-to-end path: create the integration, configure authentication, add a connection, build and test Tools, publish, wire them into a workflow, and (once built) share or move it between workspaces and environments. The mechanics of the editor itself are covered in depth in The Tool Editor; this page is the orientation around it.

When to use a custom integration

Reach for a custom integration when you want an AI Employee to act in a system Ema doesn't ship a prebuilt integration for: create a record, look something up, trigger a job. For reading documents into a Knowledge base, use a data connector instead; connectors sync content, custom integrations call APIs.

Step 1 — Create the integration

From the All tab of the Integrations page, select New integration → REST API. This opens the guided setup: a 0-of-4 checklist (About → Authentication → Connections → Tools). Start with the About step:

• Display name — what the integration is called.
• About — a short description.
• Category — defaults to Custom.

Select Create. The integration starts as a draft under Made by you in the catalog, and the remaining steps (Authentication, Connections, Tools) unlock from there.

Step 2 — Configure authentication

In the Authentication step, select Configure authentication and pick a scheme. A custom integration declares a structured set of Authentication fields under one authentication scheme:

Sub-flavours:

• Token endpoint auth method (OAuth schemes): how Ema sends your client credentials to the provider's token endpoint. Body (default) puts them in the request body; Basic auth sends them as an HTTP Basic header. Most providers accept Body; some (e.g. Workday) require Basic. Set on the connection.
• PKCE (OAuth 2.0): applied automatically; no configuration needed.
• SENT AS (API key): where Ema attaches the key on each request: Bearer token, Custom auth header, Query param, or Body param.

Adding fields — Authentication fields and credential fields

Picking a scheme gives you the minimal fields it needs, shown automatically on the connection form (for OAuth 2.0: Base URL, Authorization URL, Token URL, Client ID, Client secret, Scopes). When an API needs more, you add your own as either an Authentication field or a credential field:

• Authentication fields — their values are filled when you create the connection template, so they're shared by every connection under it. Use them for the auth setup itself. Example: a Gmail (OAuth 2.0) integration needs two extra parameters on the token exchange (Access Type and Prompt), so you add them as Authentication fields on the template.
• Credential fields — entered per connection and sent on every API call. Use them when the API needs a value attached to each request. Example: an API-key integration whose API also requires an account ID on every call: add the account ID as a credential field, and Ema includes it on every request.

The Authentication fields section displays each field in a table showing its name, type, and whether it is required or sensitive. To add a new field, select Add field: a modal opens where you set the field name, type, and options. To edit an existing field, select it from the table.

Mark sensitive fields so the UI masks them; all credentials are encrypted at rest and are never returned in API responses (the UI shows only that a value is present). See Authentication and connections for how schemes, connection templates, and live connections relate.

Viewing and editing a configured auth scheme

Once authentication is configured, the Authentication step displays a summary card showing the scheme name and the fields you have defined. To make changes (add or remove fields, or update field options), select Edit on the summary card. This opens an edit drawer on the right side of the page where you can modify the configuration and save. The summary card updates to reflect your changes when you close the drawer.

Step 3 — Add a connection

Setting up a live connection has two parts: a connection template, then a connection under it.

The connection template holds the shared setup (the base URL plus the fields your scheme needs) and an Enabled tools list. By default all of the integration's tools are enabled; click Edit and uncheck any you don't want this connection to run.

Then connect. What "connect" does depends on the connection type:

• Shared — you create one connection from the Integrations page, and everyone using the AI Employee runs its Tools through it.
• User — the connection you create is your own. Every other user of the AI Employee is prompted to sign in and create their own connection during their session, so each person acts as themselves.

For OAuth-based schemes, connecting opens the provider's consent screen; the callback marks the connection active. See Authentication and connections for the full connection model.

Step 4 — Build Tools

A Tool is a single operation an AI Employee can invoke in the connected system: "create a ticket," "look up an order," "send a message." You build Tools inside the integration's Tools step.

Every Tool, whatever its flavour, is defined by the same pieces:

• Name — the human-readable name you and other builders see.
• Description — what the Tool does. The agent reads this to decide when to call the Tool, so a clear description is what makes it get used at the right moment. Write it for the model, not just for people.
• Input schema — the typed parameters the Tool accepts. It defines what the agent (or a human-in-the-loop form) must supply, and keeps inputs validated.
• Output schema — a description of what the Tool returns, so the agent knows how to use the result.
• Write Tool — a flag marking the Tool as state-changing (a write), which changes how the agent treats it.
• Tags — optional labels for organizing Tools.

A Tool starts as a draft. You can validate and test it, and when you're satisfied, publish it. Once published, it's available for use by agents and Ema Autopilot.

Ema offers three Tool flavours; pick the one that fits the API:

• HTTP — a single declarative REST request. Use it when one request does the job.
• GraphQL — a single GraphQL query or mutation. Use it for GraphQL APIs.
• TypeScript — a sandboxed script. Use it when one request isn't enough: transforming inputs, branching on a response, paging through results, or calling several endpoints in sequence.

How to build each flavour (input/output schemas, {{...}} references, testing, and publishing) is covered in detail in The Tool Editor.

Step 5 — Test, publish, and use

Test. A Tool can be tested at any time (whether it's still a draft or already published) from the editor's Test panel. Save your changes first: the test runs against the last saved version. Then pick a connection template that has a live connection, edit the input JSON, and select Run test to call the real API; the Test result shows the response. (Validate separately checks the saved configuration for broken references, for example a {{input.X}} that no longer exists.)

Publish. Publishing makes the Tool available for selection in the AI Employee builder and to Ema Autopilot. Edits to a published Tool go live immediately, so make corrections deliberately. Or Clone it first to get a fresh draft you can change, test, and publish as a separate copy without touching the live Tool.

Wire it into an AI Employee. In the builder, add the Tool to an agent's tool list. You attach a connection template (not a specific connection), and either set the Tool's inputs or leave them for the model to infer. You can publish the AI Employee with just the template attached, but the template needs a live connection at run time:

• Shared template — if it has no connection, the run fails, prompting the user to reach out to an admin to finish the connection.
• User template — the user is prompted to finish connecting (human-in-the-loop) during the run.

Who can edit

These rules govern who can edit a custom integration and its Tools. The workspace where the integration is created is its owner workspace:

• Owner workspace admins can always edit the integration and its Tools — they don't need to be listed anywhere.
• The builder who creates the integration can edit it and its Tools.
• Any other builder in the owner workspace who needs to edit it must be added explicitly: an owner workspace admin opens the integration's Settings → Integration admins, selects Add admin, and adds them.
• If your workspace is granted access to a custom integration owned by another workspace, you can use its published Tools but can't edit the integration or its Tools.

"Integration admins" isn't a separate Ema role — it's the list of people in the owner workspace allowed to edit this particular integration.

Step 6 — Share and move an integration

Once an integration is built, you can make it available beyond the workspace where you built it using two separate mechanisms:

Share with a descendant workspace (same environment). From the integration's Settings tab, under Workspaces with access, select Grant access and choose a workspace. You can grant access only to workspaces below yours in the hierarchy (descendants). The granted workspace's admins can then install and use the integration there (setting up their own connections), while editing the integration and its Tools stays with the owner workspace's Integration admins. Deleting the integration (from the Danger zone) removes all its Tools, connections, and history and can't be undone; Ema blocks the delete while a Tool is still in use, so it can't silently break a live AI Employee.

Export and import across environments. To move an integration between Ema environments (for example dev → staging → prod), export it as a bundle and import it in the target:

• Export — from the integration's detail page, pick the Tools to include and download the bundle. The bundle carries the integration's definition and its Tools (schemas, config) but never credentials or connections.
• Import — from New integration → Import integration, upload the bundle and choose Create new (a fresh copy) or Update the integration it originally came from. Ema tracks lineage, so re-imports update the right integration instead of duplicating it.

After importing, set up authentication and connections in the target environment — credentials never travel in the bundle.

What's next

• The Tool Editor — the complete editor reference: input/output schemas, references, HTTP, GraphQL, and TypeScript details, test, validate, and publish.
• MCP Servers — add your own MCP server and use the tools it exposes.
• Data Connectors — sync external documents into Knowledge bases instead of calling an API.