Agents

Last updated: September 30, 2026

An agent is a non-human member of a Floxar account: an AI worker, an integration or a scheduled job that reads and runs your processes through Floxar’s MCP tools, with its own credentials and its own role. It runs on your infrastructure and your own AI keys; Floxar gives it an identity, a permission level and a place in the audit trail. This page is for someone building or deploying one.

What an agent is

Floxar treats an agent like any other user in the account. It has a name, a role and, where you assign them, organization or group memberships; the same permission checks apply to every call it makes, and everything it does is recorded under its identity. It appears in trail lists and trail histories like a person would, with (Agent) after its name so it is easy to tell apart.

• One agent, one account. An agent belongs to the account it was registered in and can act nowhere else. Register one agent per integration, so that rotating or deactivating its credentials disturbs nothing else.
• Three types. When you register an agent you say what it is: an AI Agent (an autonomous worker driven by a language model), an Integration (an external system, webhook or API client) or a Scheduled Job (a recurring task runner). The type describes the agent and says how its work is recorded; what it is allowed to do comes from its role.
• A role decides what it may do. An agent holds one of the account’s roles — View, Engage, Edit or Admin. An organization or group assignment carries a level of its own, which applies inside that organization or group and can give the agent more there than its account role does. Grant the least it needs; the default at registration is Edit.

Registering an agent

An account admin registers agents in the Floxar application’s Agent Registry (Automations → Agents → Agent Registry). Registration takes a minute:

1. Select Register Agent.
2. Give it a name (unique within the account), choose its type, add an optional description, and choose its role.
3. Select Register. Floxar shows the agent’s credentials once:
   • Client ID — public, of the form floxar_agent_…. Safe to log and to mention in a support request.
   • Client secret — shown only this once. Floxar keeps no copy. Store it in your secret manager, never in code, configuration files you commit, or logs.
4. Confirm that you have saved the secret. If it is lost later, rotate it (below); the old secret cannot be recovered.

Once registered, the agent can be edited (name, description, role, organization and group memberships), deactivated and reactivated, or deleted, from the same page. The registry also shows when each agent last obtained a token (Last Auth), which lags real use by up to an hour because agents cache their tokens.

Signing in

An agent does not sign in through a browser. It obtains an access token with the OAuth 2 client-credentials grant from Floxar’s token issuer, then presents the token as a bearer on every call.

Request a token

curl -X POST https://tokens.floxar.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$FLOXAR_CLIENT_ID" \
  -d "client_secret=$FLOXAR_CLIENT_SECRET" \
  -d "resource=https://mcp.floxar.com/a/$FLOXAR_ACCOUNT_ID"

The answer is a standard token response: access_token, token_type Bearer and expires_in. The details that matter:

• Two ways to send the credentials. In the form body, as above, or as HTTP Basic authentication (curl -u "$FLOXAR_CLIENT_ID:$FLOXAR_CLIENT_SECRET", with only grant_type and resource left in the body). Use one or the other; a request that carries both is refused.
• resource names what the token is for. For MCP, set it to your account URL (below); the token is then valid there and nowhere else. A token requested without resource is for Floxar’s REST API instead, and is refused at the account URL. An agent that uses both holds two tokens, one per surface.
• Tokens last 60 minutes by default. A single token cannot be revoked; deactivating the agent stops all of its tokens without waiting for them to expire. There is no refresh token: when a token is about to expire, request a new one.
• Cache the token. Each credential may request at most 30 tokens per hour by default. Keep the token in memory (or a shared cache if you run several processes), request a new one about a minute before it expires or on the first 401, and never request one per call. A process that mints on every request runs out within two minutes.
• Discovery. The issuer publishes its metadata at https://tokens.floxar.com/.well-known/openid-configuration and its signing keys at /.well-known/jwks.json. Signing keys rotate from time to time; a client that verifies tokens must look keys up by the token’s kid rather than pin one key.

The token endpoint answers failures in the standard OAuth shape, { "error": "…", "error_description": "…" }: invalid_client (401) when the client ID or secret is wrong or the agent is deactivated — stop and tell an admin, do not retry; invalid_target (400) when resource is not exactly your own account URL; and 429 with a Retry-After header when the credential has minted too often.

Connecting

An agent connects to the same URL a person’s AI client uses, the account URL:

https://mcp.floxar.com/a/<account-id>

It is shown on the Floxar application’s MCP page (Automations → Agents → MCP) and, for admins, under MCP Connections. The account id is in lower case, with nothing after it. An agent can also build it from the account_id claim of any token it requests, one without resource included, and the get_identity tool reports it.

The difference from a person’s connection is what the client sends. A person’s client starts a sign-in when the URL answers 401; an agent’s client sends its bearer token as a static Authorization header from the first request, and no sign-in happens. The account’s switch for people’s AI clients (Allow MCP connections for this account, under MCP Connections) does not apply to agents: a registered, active agent connects whether it is on or off.

Claude Code, as an agent

claude mcp add --transport http floxar-acme https://mcp.floxar.com/a/<account-id> \
  --header "Authorization: Bearer $FLOXAR_TOKEN"

The official TypeScript MCP client

const transport = new StreamableHTTPClientTransport(
  new URL(`https://mcp.floxar.com/a/${accountId}`),
  { requestInit: { headers: { Authorization: `Bearer ${await getToken()}` } } },
);

Either way the header holds a literal 60-minute token, and no client renews it for you. A header in a configuration file works for a session; a process that runs longer must mint a fresh token before the hour is up and reconnect with it — in the second example, where getToken() returns a cached token or mints one, by creating a new transport — or attach the current token to each request through the client’s own hook for that, where it has one.

Good to know once connected:

• Streamable HTTP, stateless. Each tool call is one POST. There is no session to keep, so reconnecting is just presenting a valid token again.
• Call get_identity first. It reports who the agent is, its role, its rate-limit tier and its account URL. describe_platform explains Floxar’s domain model and workflows.
• Never send an account id. Every tool takes the account from the token; an extra account_id argument is rejected.
• Writes to existing records are locked optimistically. A tool that changes a flow, step, trail or reference takes the record’s last-modified time (or, for step data, each element’s version) from your latest read, under the field its schema names, and refuses a stale value with a conflict: re-read and retry.
• REST too. The same credential works on Floxar’s REST API with a token requested without resource. MCP is the surface this page describes.

What an agent can do

Floxar’s MCP server offers 36 tools. The list an agent sees depends on its account role, raised by the level of any organization or group assignment (whose tools then work inside that organization or group only), and a tool it cannot see is also refused if called by name (PERMISSION_DENIED, naming the role it needs):

Every tool answers in the same envelope: { "success": true, "data": … }, or { "success": false, "error": { "code", "message", "errorId", "timestamp" } } with the result marked as an error. Quote the errorId when you write to support. Each tool also declares whether it reads or writes and whether it is safe to repeat; the two trail-writing tools an agent calls most take an optional key of your choosing, to send every time and reuse on a retry after a lost answer. When starting a trail, a repeat with the same origin_dedup_key from the same agent within 30 days returns the trail already started instead of a second one. When submitting step data, a repeat with the same client_intent_id and the same data returns the original outcome and writes nothing; the same key with different data is refused.

Two things have no MCP tool, by design: approving or rejecting a flow’s review, and managing the account (people, agents, settings). They are not available over MCP; use the application or the REST API.

Capacity and rate limits

• Tool calls. Each agent has a rate-limit tier; the default allows 500 calls per 30 seconds. get_identity reports the tier. Beyond it, calls are refused with 429 and a Retry-After header: wait that long, then continue. The limit is per agent, so requesting a new token does not reset it. Higher tiers are available; ask help@floxar.com.
• Tokens. 30 token requests per hour per credential (above).
• Concurrent work. An account’s plan can cap how many trails its agents work on at once. The count is trails an agent is actively working, not agents: one agent running five trails in parallel uses five slots, and a trail it has claimed but not started uses none. When the cap is reached, any call that would put one more trail into active work in an agent’s hands — starting one, resuming or reopening one, or transferring a running trail to an agent — is refused with AGENT_CAPACITY_EXCEEDED; nothing already running is interrupted, and claiming queued work is not counted. Treat it as back-pressure: wait for a trail to finish and try again. An account without a cap has no such limit.

Attribution in the audit trail

An agent is a user, so Floxar records its work the way it records a person’s, under the agent’s own identity:

• A trail an agent runs shows the agent as its executor, and every step it submits and every status change it makes is stamped with the agent’s identity and time. When a trail moves between an agent and a person, the transfer is recorded with both parties and the reason.
• A flow, step or reference an agent creates is recorded as authored by an agent or by automation, never as a person’s work.
• Every change an agent makes through MCP is written to the account’s audit record marked as made through MCP, with the tool that made it and an id that ties the change to the tool’s answer, so a failure can be traced from either side.
• An AI Agent’s work is recorded as done by an agent; an Integration’s or a Scheduled Job’s as done by automation.

Floxar keeps only a hash of the agent’s secret, and the request records it keeps never carry bearer tokens.

Rotating and revoking credentials

All of these are actions in the Agent Registry, for an account admin:

• Rotate generates a new secret, shown once, and invalidates the old one at that moment: there is no overlap, so switch your secret store before the next token request. Tokens already issued keep working until they expire, up to an hour. Rotate when a secret was lost or may have leaked; if the tokens minted before the rotation matter too, deactivate the agent as well, which puts its trails in progress back in the queue, and reactivate it once they have expired.
• Deactivate stops the agent: new token requests are refused, and tokens already issued stop working without waiting for them to expire. Its trails in progress are put back in the queue for another agent or a person to pick up. The credentials are kept, so Reactivate restores access with the same secret.
• Delete revokes the credentials permanently and cannot be undone; a deleted agent cannot be restored, only registered again as a new one. Its trails in progress are queued as on deactivation.

There is no separate switch for a single credential: an agent has one, and rotating or deactivating the agent is how it is revoked.

Agents and AI clients

People connecting an AI app and agents reach the same account URL and the same tools, and both are limited by a role. The rest differs:

If something stops

• 401 at the account URL — the token is missing, expired, or was requested without resource or for another account. Request a new token with resource set to this exact URL, once. If that token is refused too, check that the URL is your own account’s, then write to help@floxar.com with the Floxar-Request-Id response header.
• invalid_client from the token endpoint — wrong client ID or secret, the secret was rotated and this is the old one, or the agent is deactivated or deleted. Do not retry; ask an account admin.
• invalid_target from the token endpoint — resource is not exactly your account URL: check the account id, the lower case and that nothing follows it.
• 403 access_denied at the account URL — the agent cannot be served: it has been deactivated or deleted, or the account is no longer active. A new token will not help; ask an account admin.
• Fewer tools than expected, or PERMISSION_DENIED on a call — the agent’s role, or an assignment’s level, is the cause, not the connection. An admin can change the role in the Agent Registry; the agent sees the new list when it next connects.
• 429 — at the token endpoint, the credential minted too often: cache the token. At the account URL, the agent exceeded its tier: wait Retry-After seconds.
• AGENT_CAPACITY_EXCEEDED — the account’s concurrent-work cap is reached. Wait for one of the agents’ trails to finish, then retry.
• A conflict on a write — the record changed since your last read. Read again and retry with the fresh value.

For anything else, contact help@floxar.com.