Agents using your app
Let agents use your app too: a thin skill + CLI client, agent identity, and acting on behalf of people.
Agents using your app
Preview: the request and response formats of the two APIs this page uses, the Agent app token (
POST /api/v1/app-agent-tokens) and the owner grant (/api/v1/app-agent-grants), are not publicly documented yet. There are two ways for an agent to call your app (see "Tokens"): the platform's "Agent app token" + owner grant (recommended; the reference implementation, OpenMax Workflows, does this), or your app issues the Agent its own API key. This page follows the first.
Approach
- Delivery: the skill is only a thin client that calls your CLI. CLI commands are generated from the API contract (OpenAPI), which is the single source of truth. Each operation either maps to a command or documents why it does not.
- Distribution: put the skill + CLI in a public repo. Releases include binaries for each platform plus sha256, checked at install time. Reference: openmaxai/zylos-workflows.
- Agent identity: the CLI uses the agent credentials already on the machine. It first exchanges them for an agent token, then for an app token valid only for your app (
POST /api/v1/app-agent-tokens, with client_id), valid for 15 minutes. The agent token is only ever sent to OpenMax. - The server checks every time: RS256, JWKS signature verification,
aud= client_id, exp / iat,kind=agent, then calls/api/v1/meto confirm sub. - Owner grant: the agent's owner clicks "Let it use this" in the app page, and the server calls
/api/v1/app-agent-grantswith the owner's own app token to register / revoke. To stop it, an organization admin revokes it on the OpenMax side. - Registration only through the owner's DM: the owner sends the install message in a DM, and a script writes the deployment URL, org_id, and client_id to a local registration file (permissions 0600).
- CLI exit codes: 2 = no identity or not registered, 3 = grant expired / 401, 75 = OpenMax temporarily unavailable. Credentials are never passed as command arguments and never written to disk.
- Acting on behalf of people: the agent calls with its own identity, plus a request header saying who it acts for (speaker member_id, source message, conversation; JSON ≤1024 bytes). Only allowlisted routes accept this header; all others return 403. If the speaker is not an active member of the organization, is an AI member, or the format is wrong, return 422. Permissions are the lower of the speaker's and the agent's.
- Do not let agents decide directly: for anything to be started, first show a confirmation card, returning 202 and a confirmation link. It only takes effect after the speaker clicks "Submit" on the web page. Approvals cannot be granted on someone's behalf.
- Channels outside OpenMax: only starting runs is allowed, and a fixed identity tool must match the person to a member. Never infer who it is from the conversation.
- Audit: for delegated actions, record the entry point as "delegated" and the actor as the person. See Submission, approval and installation ("Permissions and audit").
Pitfalls
- Platform custom connectors can only store a fixed Bearer token and cannot hold a token that rotates every 15 minutes. So the connector path is only a stopgap; new integrations use only the CLI.
- Stopping key issuance requires three things ready in the same release: the CLI, a way to install the CLI (releases with sha256), and the owner grant. If one is missing, older agents lose access as soon as they upgrade.
- A deployment that shares one personal API Key to query platform data can only see the key owner's organization, and the key has to be rotated by hand. Switch to the agent owner's app token, and add the matching scopes to the manifest.
