Connect AI agents and custom apps
Connect AI agents and custom apps
Who can do this: any signed-in person can open Connect external agent and create a token for projects they can read. A token with Admin scope needs the Owner right on at least one of the projects it covers, unless it covers All my projects. A custom app connection is created and edited with Edit. Connecting an app by its address also puts that address on the portal allowed list, which needs Manage Members. Webhook logs are for Owner. See the .
What it's for
Your project can be driven from outside in four ways. An AI coding agent (for example Claude Code or OpenAI Codex) can read and change your project on your behalf. A developer can build a custom app for your customers or staff on top of your tables. Other systems can send events in through webhooks, and your rules can send events out. This chapter shows what you hand over in each case, what that gives the other side, and how to take it back.
You do not need to write code. You decide who gets access, and a technical person pastes the result where it belongs.
Before you start
Decide which projects the outside tool may touch. Start with one.
The address the dialog shows is the one your browser is on. Check that it is the public address of your installation before you give it to anyone.
For a custom app, the developer provides the app and the address where it runs. Ask them for that address and for the groups the app expects (customers, coaches, staff).
Needs your administrator: sign-in links for customer apps, and the Portal URL, depend on the installation's public address and outgoing email. If links point to the wrong address or never arrive, ask for "the Public App URL and outgoing email under System → Config". See .
Steps
Part 1. Connect an AI coding agent
Open the profile button in the navigator header (or on the project list). Its panel is titled "User profile & settings". Choose Connect external agent.
Under Generate new token, type a name that says where the token will live, for example "My laptop".
In the list beside the name choose how many projects the token covers. The label above the choices is Projects.
Choice | What the agent can reach |
|---|---|
This project | One project. This is the default. A dropdown lets you pick it |
Choose projects… | The projects you tick. The agent picks one of them per session. Projects you join later are not included |
All my projects | Every project you can open, checked each time the token is used. Projects you gain or lose later are followed automatically |
Under Token scope, choose User or Admin. The switch appears only if you own a covered project, or if you chose All my projects. The text below it explains the choice. See "What each scope lets the agent change" below.
Press Generate token. The token is shown once, with the warning "This token will not be shown again. Store it safely." Copy it now.
After generating, pick the tab for your tool: Claude Code or OpenAI Codex. Each shows a ready block to add to that tool's own settings file (the label above it names the file). Press Copy and give the block to the person who sets up the agent. To pin an agent to one project, add ?project= and the project's short address to the end of the MCP URL.
The third tab, Agent skill prompts, produces a text that tells an agent how to read your data through a plain web address instead. Press the Data table content button under Select API set, choose a project under Select project…, then pick a data table or spreadsheet. Copy the text from Paste into your agent skill prompt. For a spreadsheet the agent can only read.
Other AI tools that offer an MCP connector with a sign-in step can use the MCP URL at the bottom of the dialog. They send you to an approval page in your browser. It asks Which projects to grant access to (One project, Several projects, All my projects) and an Access level, then Approve or Deny. This page is in English only. What you approve there lasts 24 hours at a time and renews while the tool keeps using it. An approval left unused for 30 days lapses.
What each scope lets the agent change
An agent always acts as you. It can never do more than you can do in that project, and a change to your rights applies to its next request.
User | Admin | |
|---|---|---|
Reads and searches what you can open | Yes | Yes |
Adds, changes, deletes and restores table rows | Yes | Yes |
Writes documents, builds forms, dashboards, spreadsheets and sites, imports data, runs rules | Yes | Yes |
Publishes a site | Yes, if you can edit it | Yes |
Changes table columns and table behaviour | No | Yes |
Changes who has access, groups, customer accounts, project settings | No | Yes |
Reads connectors and their credentials; changes connectors, rules, agents and channels | No | Yes |
Exports the whole project, installs modules, invites team members | No | Yes |
The dialog describes User as discovery and row changes, and Admin as structure, access and customer accounts. Admin only takes effect in projects where you are an owner. In other covered projects the token falls back to User. Issue Admin only to an agent you trust like a deployer. The dialog calls that token a deploy credential.
Revoke a token
Open Connect external agent again. Active tokens lists every token you made, with its project coverage, creation date and last use. An Admin badge marks admin tokens.
Press the bin icon (tooltip Revoke token) on the token to remove.
Each person sees and revokes only their own tokens. An owner cannot revoke a colleague's token. To cut a colleague off, remove their rights in Users and rights. The token then reaches nothing in that project. The dialog does not list approvals made through the approval page.
Part 2. Connect a custom app
A custom app is a website a developer builds for your customers or your staff. It reads and writes your tables through the project's portal service. The Connection document is where you tell the project which of your tables feed which screens of that app.
In the navigator open the arrow beside New Document, choose Advanced, then New app connection…. Type a name in the name field. The item also appears in an item's own menu under Advanced as New app connection.
Open the new document. On first open it shows Address of the running app. Type the app's address and press Connect. The project reads what the app needs from that address. Without an address, press Paste the package instead and give the developer's package to Install template.
A header shows the template name and version, a short name of the connection, and its state: Published, or a note that it is not published. Publish… and Unpublish… change that.
On Bindings, each screen the app needs is a card. Pick the Source table that feeds it, then pick which of your columns fills each role the app names. Required roles carry a star. Choosing a table fills in the columns it can match. A table you leave as "— not bound —" gives the screen no data.
On a screen for signed-in customers, choose Who sees which rows: only their own rows (by a person column), or every row. Under "Per-group rights" you can give groups different views. The first matching row wins, and adding the first row restricts everyone who matches none.
Press Save bindings. Partial bindings save fine. Problems are listed under "Must be resolved before publishing" and "Worth checking".
Check Who can open this app. It lists the groups the app grants to. A group marked "no such group" must be created under External Users with exactly that name. A group marked "cannot open" needs Read on the connection. If the connection is not exposed to the portal, nobody can open it: switch on Publish in the external portal in External users access… on the connection. Open external users takes you to the groups.
Other tabs: Settings holds values the app asks for (Save settings). Connectors appears when the app needs an outside service such as payment: choose which of your connectors fills each slot. Notifications shows what the app notifies members about and, under Recently sent, what each channel actually did. Deployment serves the app on a project address or your own domain with the same Publish to web panel as a site (see ) and holds Where login links land and Default app.
Press Publish… when the header says "Ready to publish". Publishing matters only for screens open to anyone without signing in. Screens for signed-in people work while unpublished.
Some apps ship their own tables, columns and dashboards. After Connect you may see "This app ships a back-end configuration". Review changes shows what would be created or changed and changes nothing. Then Install (or Apply changes) applies it. Not now postpones it. Later, Check for configuration on Deployment asks the app again. The page says rows are never touched and nothing is deleted.
Careful: pressing Connect adds the app's address to your project's allowed list for customer apps (CORS) if you have
Manage Members. The editor does not announce it. An entry on that list is a trust grant: any page on that site can read what a signed-in customer of this project can see. Check the address, remove it under External Portals → CORS settings if the app moves, and read the warning in . Never add shared hosting or sandbox sites.
What to give the developer: the project's short address and the connection's short name (shown in the header), the groups and tables you intend to expose, and your decision on which screens are open to anyone. The developer's reference is the business and integrator guide (Part B) and the platform concepts. They use a typed client, @juxtaboard/portal-client (package notes), built from the portal service's published contract. The installation serves that contract at /api/portal/openapi.json, without a sign-in.
A staff app works the same way, with one difference. Staff sign in with their normal team account and are handed back to the app, so the app's address must be on the same allowed list.
Part 3. Webhooks in and out
Webhooks are part of Automations, which needs Owner. The full set of options is in .
Into your project: give a rule the trigger Inbound webhook. After saving, copy the Webhook URL and give it to the sending system. Anyone holding it can fire the rule. Add a Signing secret (optional) if the sender signs its requests. Regenerate the URL if it leaks.
In the rule, under Recent deliveries, every request that arrived is listed. A row says Accepted, with the run it started, or Rejected — bad signature. Open a row to see the sender's address, whether a signature was present, and the start of the body. Send test payload adds a sample.
Out of your project: a Call webhook action posts to an address you choose. In Automations open Webhook deliveries. The columns are Automation, status, Created, Attempt and HTTP. The statuses are Pending, Succeeded, Failed and Abandoned. Press a row for the Target URL, HTTP status, Payload, Response body and Error. Replay sends it again. Refresh reloads the list.
Notifications from payment providers and messengers use the installation's own addresses, set up in and .
Part 4. Credential requests and builder keys
When an assistant or an Admin-scope agent sets up a messaging channel or a connector, it does not ask you for the secret in chat. It gives you a link to a page titled Enter credentials. Type the values and press Save and connect. The agent never sees them. Details, the rights needed and the 7-day lifetime are in .
Needs your administrator: the keys that connect the installation to the portal builder (the Portal builder menu item, which owners do not see) live in System → Config on the Security tab, in a panel called "Juxtaboard Builder Bridge". Only an administrator opens it. Regenerating the keys breaks a builder that still uses the old ones. Owners never handle these keys.
How to check it worked
Agent: ask it to list your projects or read a table. The token's line in Active tokens then shows a "last used" date.
Webhook: Send test payload, then watch Recent deliveries show Accepted.
Undo / what can go wrong
Related
· · · · · · · · · For developers: business guide, platform concepts