Registering an agent

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 article is for you if you are building or deploying one.

To work in Floxar from an AI app you use yourself, such as Claude, ChatGPT or Cursor, you do not need an agent: you sign in from the app with your own login. See Connecting an AI client. Register an agent when software acts on its own, under an identity of its own. Agents and AI clients compares the two.

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.

Role	What the agent can do
View	Find and read flows, steps, references and trails. It cannot start or change anything, except to report that it found no flow for a task it was given.
Engage	Everything View allows, and run work: start trails, submit step data, move a trail forward, pause, complete or abandon it, hand it off, or claim queued work.
Edit	Everything Engage allows, and author: create and change flows, steps, connections and references, and change a trail's details.
Admin	The same tools as Edit. No MCP tool needs Admin, so Edit is the widest role an agent needs for MCP.

Registering an agent

An account admin registers agents in the Agent Registry of the Floxar application (Automations, then Agents, then 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_<your-id>. It is 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, in configuration files you commit, or in logs.
4. Confirm that you have saved the secret. If it is lost later, rotate it (see "Rotating and revoking credentials" 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, tokens.floxar.com, then presents the token as a bearer token on every call.

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 access token is a signed JWT. 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; the token is then valid there and nowhere else.
• Tokens last 60 minutes by default. There is no refresh token: when a token is about to expire, request a new one.
• Discovery. The issuer publishes its metadata at https://tokens.floxar.com/.well-known/openid-configuration and its signing keys at https://tokens.floxar.com/.well-known/jwks.json. Signing keys rotate from time to time; if you verify tokens yourself, look keys up by the token's kid rather than pinning one key.

One credential, two tokens

Every Floxar token is for exactly one place, named when you request it:

Token	How you request it	Where it works
MCP token	With resource set to your account URL	Floxar's MCP tools at your account URL, and nowhere else
REST token	Without resource	Floxar's REST API; refused at your account URL

An agent that uses both MCP and the REST API holds two tokens from the same credential, and caches each separately for its own lifetime. Both count against the same token-request limit. MCP is the surface this article describes; the REST API and its reference are covered separately.

Token lifetime and caching

• Cache the token. Each credential may request at most 30 tokens per hour by default. Keep the token in memory, or in a shared cache if you run several processes, and never request one per call. A process that requests a token on every call runs out within two minutes.
• Renew before it expires. Request a new token about a minute before the current one expires, or on the first 401. If the new token is refused too, stop and investigate rather than looping.
• A single token cannot be revoked. Deactivating the agent stops all of its tokens at once, without waiting for them to expire (see "Rotating and revoking credentials").
• Budget for starts. A process that looks up its account URL when it starts, with a REST token, then requests its MCP token, uses two token requests per start.

Token errors

The token endpoint answers failures in the standard OAuth shape:

{ "error": "invalid_client", "error_description": "<why>" }

• invalid_client (401): the client ID or secret is wrong, or the agent is deactivated or deleted. Stop and tell an account admin; do not retry.
• invalid_target (400): resource is not exactly your own account URL.
• invalid_request (400): the request is malformed, for example it carries both ways of sending the credentials. Fix the request; do not retry it unchanged.
• 429 with a Retry-After header: the credential has requested too many tokens. Wait, and cache the token.

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 MCP page of the Floxar application (Automations, then Agents, then MCP) and, for account admins, under MCP Connections in the account settings. The account id is in lower case, with nothing after it. An agent can also build the URL from the account_id claim of any token it requests, 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 acme-floxar 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 request a fresh token before the hour is up and reconnect with it (in the second example, where getToken() returns a cached token or requests 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. Send one request per POST; batches are refused.
• 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: read again and retry.
• Permissions are checked on every request. A change to the agent's role applies immediately to what a tool call is allowed to do; a client may keep showing the tool list it fetched when it connected until it reconnects.

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). A tool it cannot see is also refused if called by name, with PERMISSION_DENIED naming the role it needs.

Role	Tools	Adds
View	17	get_identity and describe_platform; search and read flows, steps, references and trails; report an unmatched context
Engage	23	Create and run trails: submit step data, move forward, pause, resume, complete, abandon, hand off or claim queued work
Edit and Admin	36	Create and change flows, steps, connections and references; change a trail's name, priority and categories

Every tool answers in the same envelope, and a failure also marks the result as an error:

{ "success": true, "data": "<result>" }
{ "success": false, "error": { "code": "<code>", "message": "<text>", "errorId": "<id>", "timestamp": "<time>" } }

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:

• 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.
• 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). Use the application or the REST API for those.

Capacity and rate limits

• Tool calls. Each agent has a rate-limit tier; the default allows 500 calls per 30 seconds, and 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 by default (see "Token lifetime and caching").
• 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 issued 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.

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 account 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 requested too many tokens: 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.

Last reviewed: 2026-09-30