HTTP API

This page: call an app's actions from an external system over HTTP. Use it when a support-desk bot, a CI job, a cron script, a Lambda, or any backend service needs to invoke your app without a browser and without an MCP client.

Every defineAction in actions/ is already an HTTP endpoint. The frontend calls it through useActionQuery / useActionMutation with a session cookie, but the same route accepts an Authorization: Bearer token, so anything that can make an HTTPS request can call it. There is no separate "public API" to build and no REST wrapper to maintain — the action you wrote for the agent and the UI is the API.

When to use this surface

Pick HTTP when the caller is code and already knows exactly which operation it wants:

HTTP is the cheapest of the three: one request, one JSON body, one JSON response, no handshake, no session, no model in the loop. MCP and A2A both sit on top of the same actions — reach for them when the caller needs a tool catalog or the whole agent loop, not a single known operation.

Mint a token

Tokens come from the connect CLI. There are two kinds, and the choice matters.

Personal token — bound to the person who runs the command. Use it for your own scripts and local development.

npx @agent-native/core@latest connect https://clips.example.com

This opens a browser sign-in, then writes the token into your local MCP client configs. Rows the token creates are owned by you.

Org service token — bound to a synthetic, organization-owned identity rather than a person. Use it for anything that must keep running after people change teams: CI, a support-desk bot, a scheduled integration.

npx @agent-native/core@latest connect https://clips.example.com \
  --service-token support-desk --ttl-days 90

The command still authenticates you in the browser first — minting requires org owner or admin — but the resulting token's subject is svc-support-desk@service.<orgId>. It survives you leaving the org or revoking your own personal tokens, and the rows it creates are org-scoped, so every org member can see them. The token value is printed exactly once and is never written to a local config file; copy it straight into your secret store.

Personal tokens default to 365 days in the CLI device flow; to choose a lifetime from 1 to 365 days, use the app's Connect page at https://<app>/mcp/connect. Org service tokens also default to 365 days and accept --ttl-days values between 1 and 3650. If a machine cannot open a browser, the app's Connect page is the fallback: sign in there, copy the token, and pass it with connect <url> --token <token> or paste it directly into your secret store.

For a self-hosted, single-tenant app where per-person identity does not matter, the static ACCESS_TOKEN / ACCESS_TOKENS environment variables are the simplest option — see Authentication — Static MCP Bearer Tokens.

Call an action

The route is POST /_agent-native/actions/<action-id>. The action id defaults to the action's filename, so actions/import-loom-recording.ts mounts at /_agent-native/actions/import-loom-recording.

The request body is the raw JSON of the action's zod schema — no envelope, no { args: ... } wrapper. The response is the action's return value serialized bare at the top level, not wrapped in { result: ... }.

curl -sS -X POST \
  https://clips.example.com/_agent-native/actions/import-loom-recording \
  -H "Authorization: Bearer $AGENT_NATIVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.loom.com/share/EXAMPLE_SHARE_ID"}'

{
  "recordingId": "rec_8f2a91",
  "title": "Checkout fails on Safari 17",
  "status": "imported"
}

GET actions and query params

An action that declares an http override is reachable with the method it names, and GET args arrive as query params instead of a JSON body:

export default defineAction({
  description: "Get details for a lead.",
  schema: z.object({ leadId: z.string() }),
  http: { method: "GET" },
  run: async ({ leadId }) => {
    /* ... */
  },
});

curl -sS \
  "https://crm.example.com/_agent-native/actions/get-lead?leadId=lead_123" \
  -H "Authorization: Bearer $AGENT_NATIVE_TOKEN"

http: { path: "..." } changes the mounted URL for direct HTTP callers only, and http: false removes the endpoint entirely. See Actions — HTTP config for the full option set.

Errors

Every failure returns { "error": string } with an appropriate status:

Treat a 500 as "check the app's logs", not "read the error text". Actions that want to return a specific, user-facing failure should throw with an explicit statusCode below 500; those messages do come back verbatim.

CSRF and CORS

A cookieless server-to-server call skips CSRF entirely — there is no session cookie to confuse, so there is nothing to protect against. You do not need to fetch a CSRF token, and you should not send cookies.

Cross-origin calls from a browser are different: they need an allowlisted origin. If you are calling from browser JavaScript on another domain, configure the app's CORS allowlist first. Server-side callers are unaffected.

Worked example: a support-desk bot

A support-desk bot watches inbound tickets. When a customer attaches a Loom share link to a bug report, the bot imports it into Clips so the support team can comment on the recording, clip the relevant 20 seconds, and attach it to the engineering issue.

1. Mint a token the bot owns. Run this once, as an org owner or admin:

npx @agent-native/core@latest connect https://clips.example.com \
  --service-token support-desk --ttl-days 365

Copy the printed value into the bot's secret store as AGENT_NATIVE_TOKEN. It is shown once and never stored by the app.

2. Call the action when a ticket arrives.

const res = await fetch(
  "https://clips.example.com/_agent-native/actions/import-loom-recording",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.AGENT_NATIVE_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ url: shareUrl }),
  },
);

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`Clips import failed (${res.status}): ${error}`);
}

const { recordingId } = await res.json();

3. Link back to the recording. Post https://clips.example.com/r/${recordingId} into the ticket thread. Because the bot used an org service token, the recording is org-scoped: every teammate who opens that link sees it, and it does not disappear when the person who set up the bot changes teams.

The action ran exactly as it would have from chat or the UI — same validation, same access checks, same app state write that focuses the new recording for anyone who has the app open.

Lifetime, rotation, and revocation

Tokens are JWTs signed by the app and bound to that app's audience. A token minted for one app cannot call another.

• Lifetime — 365 days by default, --ttl-days between 1 and 3650. Shorter is better for anything that runs unattended.
• Rotation — mint the new token, deploy it to the caller, confirm traffic is flowing, then revoke the old one. There is no in-place rotation; the two tokens are independent and can overlap.
• Revocation — every token carries a jti, and revocation is a jti check on every request, so a revoked token stops working immediately. Use the list-org-service-tokens action to see names, who minted them, and last-used timestamps, then revoke-org-service-token with the id. Both are owner/admin-gated for writes; any org member can list.
• Recovery — the token value is never stored, only its jti. If you lose it, mint a new one and revoke the old.

Because list-org-service-tokens reports lastUsedAt, it doubles as a cleanup tool: anything that has not been used in months is a candidate for revocation.

Service principals

Each org service token is a service principal, and a governance record says who answers for it and what it may do. Owners and admins set it when minting (create-org-service-token takes optional ownerEmail, team, riskTier, purpose, and allowedActions) and change it later with set-service-principal-policy. list-org-service-tokens returns each principal's record in principals.

• Grant — tools/list shows only the granted actions, and any call outside the grant is refused, whether it arrives over MCP, an HTTP action route, or an agent run the principal started with ask-agent or ask_app. Agent built-ins such as tool-search and view-screen are covered too, so name them in the grant if the principal needs them. The grant narrows what the member role already allows; it never adds access.
• Suspend and resume — set-service-principal-lifecycle with suspended refuses the principal on every request, refuses new agent runs for it, and aborts its in-flight runs. active resumes it. The MCP connect page (/mcp/connect) has the same suspend and resume controls. retired also revokes its tokens and cannot be undone.
• Ungoverned — a service token minted before governance has no record. It stays active and unrestricted until an admin sets a policy.
• Fails closed — if the policy cannot be read, the request is refused with a 503, never admitted.

These actions are owner/admin-only and are not callable by the agent, so neither an agent nor a service token can loosen its own grant.

When it 403s

A 401 means the token was not accepted at all. A 403 means the token was accepted and the request then failed an access check — a different problem with a different fix.

What's next

• Actions — define the operation once; HTTP, MCP, A2A, CLI, and the UI all call the same one
• Authentication — session auth, orgs, and static ACCESS_TOKEN bearers
• MCP Server — the tool-catalog surface these tokens are audience-bound to
• A2A Protocol — agent-to-agent delegation between agent-native apps
• Security — data scoping, access guards, and secret handling