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: Member, 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
Member	Nothing beyond signing in: it is served only the tools every agent has (see What an agent can do), and a tool that needs a role is refused. Member is the membership an organization or group assignment needs above it, so an agent that works only inside one organization or group holds Member on the account and its working role on that organization or group. The Agent Registry offers View to Admin and shows a Member agent with no role; set Member through the REST API.
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	Everything Edit allows, and administer the account: its administration feeds, settings, users and scopes.

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.
• scope_id is optional, and only the Secrets Vault reads it. It names the level whose secrets the token is for: the id of an organization or group of your account, or the word root for the account level. Leave it out unless the agent reads secrets from the Vault (see "One credential, two tokens").
• 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.

A token for the Secrets Vault

The Secrets Vault accepts a REST token only when the request for it also named a level, in the form field scope_id:

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

scope_id in the request	What the Secrets Vault does with the token
The id of an organization or group	Reads the secrets kept at that level
The word root, in lower case	Reads the secrets kept at the account level
Not sent	Refuses the token with 401

• A token without scope_id works everywhere else. The REST API and MCP do not read it, so an agent that never uses the Vault requests its tokens as before.
• Naming a level grants nothing. The token endpoint checks only the form of the value. The Vault releases a secret only where an account admin has granted the agent that secret at that level.
• One token per level. An agent that reads secrets at several levels requests one token for each and caches them separately. Each is one token request against the account's allowance.
• The request decides, nothing else. The agent's role, its organization and group assignments and the level it is administered from play no part in which level a token reaches.

Using the Secrets Vault from an agent covers the rest: grants, the recipient key and what the Vault's refusals mean.

Token lifetime and caching

• Cache the token. Token requests are limited per account, by plan: the account's agents share an hourly allowance of six times the plan's per-minute request budget (180 an hour on Free, 1,500 on Starter, 6,000 on Team, 21,000 on Scale), and an account admin may also set a lower cap on a single credential. 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 spends the whole account's allowance and blocks its other agents. Over the limit, a request is refused with 429 and a Retry-After header.
• 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. A scope_id that is neither a level's id nor the word root is refused this way too, with the description scope_id must be a scope id (a UUID) or the word root: an empty value, ROOT in upper case, a malformed id, or the field sent twice. 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, on the Configuration tab of the MCP page in 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, in Account Settings under MCP, Configuration) 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.

If your agent uses an MCP client other than these two, or you want one verified, write to help@floxar.com.

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, the organizations and groups where it holds a grant of its own, its account URL and its account's agent limits (agent_limits: the plan, the request budget and the concurrent capacity, each with whether it comes from the plan or from a limit set for the account). Name a level with scope_id and it also reports the agent's role there and where that role comes from (working_scope): a grant on that level, one inherited from a level above it, or the account role. 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.
• Only trail writes are locked optimistically. A tool that changes a trail, step data included, takes the trail's last-modified time from your latest result for that trail, under the field its schema names, and refuses a stale value with a conflict: read again and decide again. Every trail write returns the trail's new last-modified time, and writing step data moves it too: send the returned value with your next trail write. Writes to flows, steps and references take none: the last write wins.
• 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

The tools an agent sees depend 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	Adds
Member	get_identity, describe_platform and the operation tools (describe_operations, read_operation, execute_operation); each operation still checks the role it needs
View	Search and read flows, steps, references and trails; report an unmatched context
Engage	Create and run trails: submit step data, move forward, pause, resume, complete, abandon, hand off or claim queued work
Edit	Create and change flows, steps, connections and references; review, approve and promote content; change a trail's name, priority and categories
Admin	Administer the account through read_admin_operation and administer_operation

Each role has every tool of the roles above it in the table. The tool reference lists every tool with the role it needs, generated from the tools as Floxar's MCP server registers them: reading content, running trails, authoring content and administration.

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.

An Admin agent administers the account with the two administration tools, which run the account's administration operations by the id describe_operations lists; see the administration tools. Approving and rejecting are available to agents, for a flow's review and for bit promotions, where the Agents may approve promotions setting is on (the default); see Approval.

Capacity and rate limits

Beta. Agent limits are in beta. Floxar may modify these limits at any time.

Two limits apply to an account's agents, and both belong to the account, not to any one agent: a request budget and a concurrent agent capacity. Their values depend on the account's plan; for higher limits, ask help@floxar.com. To see the values in force for your account:

• In the application. An account admin sees them in the Agent capacity panel on the Agents page, as agent requests per minute and concurrent agent trails.
• From an agent. get_identity reports them under agent_limits: request_budget and concurrency, each with its value and whether it comes from the plan or from a limit set for the account.

How each limit works, and what happens when it is reached:

• Request budget. Every request any of the account's agents makes, REST or MCP, draws on one budget per account, counted over a rolling minute. The agents share it, so registering another agent or requesting a new token adds nothing. Over the budget, a call is refused with 429 and a Retry-After header: wait that long, then continue.
• Tokens. An hourly token allowance per account, six times the plan's per-minute request budget and shared by the account's agents, plus any cap set on a single credential (see "Token lifetime and caching"). Token requests do not draw on the request budget.
• Concurrent work. The concurrent agent capacity is how many trails the account's agents may hold in active work at once. The count is trails, not agents: one agent running five trails in parallel uses five slots, and a trail it has claimed but not started uses none. Claiming queued work is never refused, and nothing already running is interrupted by a call that is refused or deferred. What happens when a call 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) at the limit is the account's overflow mode, which an account admin chooses on the Agents page:
  • Queue new work (the default). A new trail is still created, but queued and unassigned for any worker to claim when a slot frees, while starting, resuming or reopening an existing trail is refused with AGENT_CAPACITY_EXCEEDED.
  • Reject. Every such call is refused with 429 AGENT_CAPACITY_EXCEEDED; wait for a trail to finish and try again.
  • Displace. The call succeeds, and one of the account's agent trails that has been active for at least the account's minimum goes back to the queue, unassigned; with none eligible, the result is the same as queueing new work.
• A deferred create is accepted work, not an error. The answer is a success: the trail comes back with status queued and no assignee, and agent_capacity (in the tool's data, or in meta over REST) carries code AGENT_CAPACITY_DEFERRED. Do not retry the create; the trail exists and will be picked up from the queue.
• A displaced trail returns to the queue. It keeps its work so far, and any worker with claim rights, its former agent included, can claim it again. Until then, that agent's next write to it fails: the trail is reported as queued, or, for a View or Engage agent, as not found, and once another worker has claimed it the write is refused because an agent works only the trails assigned to it. Re-read the trail before treating any of these as a fault.

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.
• 401 from the Secrets Vault: the token is expired, was requested with resource, or was requested without scope_id. Request a REST token that names the level whose secrets the agent needs (see "A token for the Secrets Vault").
• invalid_request naming scope_id from the token endpoint: the value is not a level's id or the word root in lower case. Correct it; the same request will be refused again.
• 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 agent at Member everywhere sees only the tools every agent has. 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 account's agents together exceeded the account's request budget: wait Retry-After seconds.
• AGENT_CAPACITY_EXCEEDED: the account's concurrent agent capacity is reached. Under the default mode only starting, resuming or reopening an existing trail is refused, and a new trail is created queued instead; under Reject every such call is refused. 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-11-10