# Floxar Documentation

> Public documentation for Floxar: integrating AI clients and agents, using the platform, and authoring good content.

This file contains all documentation content in a single document following the llmstxt.org standard.

## AI features

Floxar has two AI features with separate jobs. The AI Assistant answers your questions from your organization's content and about Floxar itself, shows the sources it used, and never changes anything. The Flow Designer drafts new flows and improvements to existing ones as proposals, and nothing is saved until you accept.

### [The AI Assistant](/ai-features/the-ai-assistant/)

The AI Assistant is a chat built into Floxar for asking questions in plain language. It answers from your organization's own process content — your flows, bits, and references — and it can also explain how Floxar itself works. Every answer is grounded in real content, and the Assistant shows you exactly which sources it used.

### [The Flow Designer](/ai-features/the-flow-designer/)

The Flow Designer is Floxar's AI drafting partner for people who build content. Describe a process in conversation — or attach the documents that describe it — and the Designer drafts a flow for your review. It works as a strict two-step: the Designer proposes, you decide. Nothing is saved to your account until you accept.

---

## The AI Assistant

The AI Assistant is a chat built into Floxar for asking questions in plain language. It answers from your organization's own process content — your flows, bits, and references — and it can also explain how Floxar itself works. Every answer is grounded in real content, and the Assistant shows you exactly which sources it used.

### What you can ask

Ask about your organization's processes the way you would ask a colleague: "Which flow covers customer onboarding?" or "What are the steps to close out an audit case?" The Assistant searches your organization's flows, bits, and references and builds its answer from what it finds. It only ever uses content you already have permission to view — it never surfaces anything your role can't see.

You can also ask about Floxar itself: what bits, flows, trails, and references are, how features work, and how to write content that works well. When you ask the Assistant to actually create or restructure content, it will explain that authoring is the Flow Designer's job and point you there.

### Answers show their sources

Every answer lists the sources the Assistant actually used — the specific bits, flows, and references it read to answer you. Citations are clickable: select one to open that content and check the answer against it. The list is limited to sources the answer really drew on, so what's cited is what was used.

### When your content doesn't cover something

The Assistant doesn't guess. If it searches and finds nothing that answers your question, it says so plainly and suggests rephrasing or asking about a specific flow, bit, or reference. It never invents process steps, and it quotes numbers and named steps exactly as your content states them.

### The Assistant reads — it never writes

The Assistant is strictly read-only. It can search and read your content to answer questions, but it cannot create, edit, or delete anything. No matter what you ask, your flows, bits, and references stay exactly as they are.

That also means the Assistant is not the tool for authoring. If you want content created or changed — a new flow drafted from a document, missing steps added to an existing flow, a bit rewritten — that is the job of the Flow Designer, which drafts changes as proposals you review and approve. See the Flow Designer article for how that works.

### Your conversation continues where you left off

Your conversation with the Assistant is saved as you go. Close the chat, reload the page, or sign in from another device — the conversation picks up where you left off, with its history intact. When you want a clean slate, start a new conversation. While an answer is being written you can stop it, and you can copy any answer to use elsewhere.

### Usage and availability

Assistant usage draws on your account's credits. If your account runs low, the Assistant will let you know.

The Assistant is enabled per account. If you don't see it in Floxar, it may not be enabled for your account yet.

*Last reviewed: 2026-07-28*

---

## The Flow Designer

The Flow Designer is Floxar's AI drafting partner for people who build content. Describe a process in conversation — or attach the documents that describe it — and the Designer drafts a flow for your review. It works as a strict two-step: the Designer proposes, you decide. Nothing is saved to your account until you accept.

### Drafting a flow from documents or a description

Start a conversation and tell the Designer what you want to build. You can attach process documents you already have — such as PDFs, Word documents, or plain text — or simply describe the process in your own words.

Before drafting, the Designer discusses scope with you: what the process is for, who carries it out, where it starts, and where it ends. This isn't a fixed questionnaire — it asks what it needs based on what you've told it and what's in your documents. When the scope is clear and you give the go-ahead, it drafts a proposed flow: the bits, the connections and branching between them, and the starting point.

### Improving existing flows and bits

The Designer can also work on content you already have:

- **Filling gaps in a flow.** Point the Designer at an existing flow that's missing steps. It reads the flow as it is today and proposes the missing bits and connections as additions — your existing bits are not modified. Before it starts, you can tell it what to focus on.
- **Improving a bit.** Ask the Designer to improve a bit, and it proposes a rewrite of that bit's title and text. Any interactive elements in the bit are preserved exactly as they are — the rewrite touches the words, not the workings. If a bit contains content it can't safely rewrite (tables or embedded media, for example), it declines rather than risk degrading your content.

When you're improving existing content, the Designer works from the flow itself — documents aren't used in those conversations.

### Proposals: nothing is saved until you accept

Everything the Designer produces is a proposal. You review it before anything happens:

- **Accept** it, and the proposed content is saved to your account.
- **Reject** it, and nothing is saved — your content is untouched.
- **Keep discussing.** Not quite right? Tell the Designer what to change and let it revise before you decide.

The Designer cannot save anything on its own. The only way its work reaches your account is your explicit acceptance.

### Availability and usage

The Flow Designer is an authoring tool, so it's available to users who can edit content. Usage draws on your account's credits.

### Assistant or Designer?

Floxar has two AI features, and the split is simple:

- **Ask questions → AI Assistant.** Want to find, understand, or check something in your organization's content, or learn how Floxar works? The Assistant answers with cited sources and never changes anything.
- **Create or change content → Flow Designer.** Want a flow drafted, gaps filled, or a bit improved? The Designer drafts it as a proposal for you to accept or reject.

If you start in the wrong place, no harm done — asking the Assistant to build something gets you a pointer to the Designer, and your content stays untouched either way.

*Last reviewed: 2026-07-28*

---

## Concepts

Start here to learn the ideas the rest of the documentation builds on. Floxar turns your team's processes into interactive, step-by-step workflows made of bits, flows, trails and references, and keeps a record of every run. These articles also show you the main areas of the app, and how organizations, groups and roles shape what you can see and do.

### [What is Floxar? Bits, flows, trails, and references](/concepts/what-is-floxar/)

Floxar is a platform for turning your team's processes into interactive, step-by-step workflows. Instead of writing a procedure into a static document that people read once and set aside, you build it as a guided experience: a person follows the process one step at a time, records their answers and decisions as they go, and Floxar keeps a complete record of every run. Four concepts make this work: bits, flows, trails, and references.

### [Navigating Floxar: the main areas of the app](/concepts/navigating-floxar/)

When you sign in to Floxar, you land on the Home page, and a navigation bar stays with you throughout the app. This article walks through the main areas and what each one is for, so you know where to go for any given task.

### [Organizations, groups, and scopes: how a Floxar account is organized](/concepts/organizations-groups-and-scopes/)

Every Floxar customer has an account — the top-level home for all of a company's people, content, and activity. Inside an account, people and content are organized using organizations and groups, known collectively as scopes. Understanding this structure explains what you can see and do in Floxar, and where the content you create ends up.

---

## Navigating Floxar: the main areas of the app

When you sign in to Floxar, you land on the Home page, and a navigation bar stays with you throughout the app. This article walks through the main areas and what each one is for, so you know where to go for any given task.

### Home

Home is your starting point for getting to work. It surfaces the flows that matter to you right now: work you were recently in the middle of and can continue, flows that are popular across your team, and the flows you have marked as favorites. Selecting a flow from Home takes you straight into running it.

### Search

Search is where you go when you know what you are looking for. You can search flows and bits by name, description, or content, switch results between flows and bits, and re-run recent searches. Results respect your access, so you only see content you are allowed to open.

### Library

The library is home to reference material — the read-only supporting documents (policies, guides, FAQs) that back your processes. You can search and filter the library and view results as cards or a table. Users with editing permission can also add new references here.

### Trails

The Trails area lists execution records — the trails produced whenever someone runs a flow. You can filter them by status, date range, and assigned person, switch between card and table views, and open a trail to resume or review it. As everywhere in Floxar, you only see trails you have permission to access.

### Queue

The queue holds unassigned work: trails that are waiting for someone to pick them up. You can search and filter the queue to find the right item, gauge how large the backlog is, and open an item to claim it and start working.

### Analytics

Analytics answers the question "how is my operation performing?" It presents metrics and visualizations — such as completion and progress measures — over a date range you choose, organized into panels. It is aimed primarily at people overseeing process performance, and it is also useful to content authors evaluating how well their flows work.

### Notifications and announcements

The bell icon in the navigation bar opens a panel of recent notifications, and the Notifications page holds the full history, where you can page back through older items and mark everything as read. Announcements are broader messages published within your account: everyone sees the announcements addressed to them, and users with editing permission can compose and manage them.

### Creating and editing content

If you have editing permission, you can create new flows and bits and edit a bit's content in the rich-text editor. There is also a guided tool for creating many trails at once from a spreadsheet file, which is useful when setting up a batch of work.

### Profile and account administration

Your profile page shows your name, email, and an overview of what you can access; if you belong to more than one account, you can switch between accounts from there. Administrators additionally have account management areas covering account settings, the organization and group structure with its access assignments, the user roster (including invitations and role assignments), registered automated agents, and an audit history of account activity.

*Last reviewed: 2026-09-23*

---

## Organizations, groups, and scopes: how a Floxar account is organized

Every Floxar customer has an account — the top-level home for all of a company's people, content, and activity. Inside an account, people and content are organized using organizations and groups, known collectively as scopes. Understanding this structure explains what you can see and do in Floxar, and where the content you create ends up.

### The hierarchy: account, organizations, groups

The structure has three levels. The account sits at the top and typically represents your company or a major business unit. Organizations are subdivisions directly under the account — often departments, regions, or business lines. Groups are the most granular unit: teams or functional groups that always live inside an organization. Administrators manage this structure, and account-level settings control whether organizations and groups can be created at all; a group can only exist once at least one organization does.

### Access levels

Access in Floxar is granted as a role at a specific level of the hierarchy. From most to least privileged, the roles are: Admin (full management, including user administration), Edit (create and modify content), Engage (run workflows and interact with content), View (read-only access), and Member (belongs to a level but has no access rights on its own). You hold one role per level you are attached to.

### Permissions inherit downward

A role granted at one level automatically applies to everything beneath it. Admin on the account means Admin in every organization and group inside it. Edit on an organization means Edit in all of that organization's groups. Grants at lower levels are additive, and when several grants apply to the same place, the most privileged one wins. For example, someone with View on the account and Edit on one organization can read content anywhere in the account, but can create and modify content only within that organization and its groups.

The Member role exists to connect you to the levels above the place where your real access lives. A person might be a Member of the account and a Member of an organization, with an Edit role granted on a single group inside it — meaning they can author content in that group but have no access elsewhere. This is also why someone can appear in the account's user list while holding no meaningful access yet: they belong, but their working role has not been granted.

### Content belongs to one place

Content follows the same structure. Every flow, bit, and reference belongs to exactly one place in the hierarchy: the account level, where it is available to everyone in the account, or a specific organization or group, where it is visible to that scope's members. Content does not cross between scopes — scoping is how one department's processes stay out of another department's way while shared, account-wide content remains available to all.

### Your working context

Day to day, you work within a selected scope, called your working context. Your working context determines which content appears in listings and which scope newly created content is placed in by default. You can switch your working context from within the app whenever you need to work in a different part of the hierarchy. If your access to the selected scope is ever removed, Floxar automatically falls back to the account level, so you are never left stuck in a place you can no longer see.

*Last reviewed: 2026-07-28*

---

## What is Floxar? Bits, flows, trails, and references

Floxar is a platform for turning your team's processes into interactive, step-by-step workflows. Instead of writing a procedure into a static document that people read once and set aside, you build it as a guided experience: a person follows the process one step at a time, records their answers and decisions as they go, and Floxar keeps a complete record of every run. Four concepts make this work: bits, flows, trails, and references.

### Bits: the building blocks

A bit is the smallest unit of process content in Floxar — a single, focused step. Each bit holds rich content such as text, headings, lists, images, and video, together with interactive elements like checklists, dropdowns, text fields, and date pickers. These elements are what make a step actionable rather than just readable: when someone works through the step, what they select or type is captured automatically. Bits are independent building blocks — a bit is authored and maintained on its own, and the same bit can be connected into more than one flow, so a shared step only needs to be written once.

### Flows: steps connected into a process

A flow is a navigable sequence of connected bits — in other words, a workflow or process template. Every flow begins at a designated start bit. From each bit, connections point to the possible next steps; when a bit has several outgoing connections, the person running the flow chooses which path to take. This is how a single flow can handle branching situations, such as different handling for different case types. Flows can also be tagged with categories, which makes them easier to organize, filter, and find.

### Trails: a record of every run

A trail is the record of one person's journey through a flow — a single run of the process. When you start a flow, Floxar creates a trail for you. As you move from step to step, the trail captures each bit you visited, the answers and inputs you provided, and the time you spent. Trails are flexible about how work actually happens: you can pause a trail and resume it later, hand it over to a colleague, or leave it in a shared queue for someone else to pick up. A trail ends when it is completed or abandoned, and its full history remains available afterwards so the work can always be reviewed.

### References: supporting knowledge

References are read-only supporting documents that back up your process content — policies, guides, FAQs, definitions, and similar material. They are written with the same rich-text tools as bits, but they contain no interactive elements and are never steps themselves. Instead, references are linked to bits, and while running a flow you can open a linked reference in an overlay to check the details without losing your place. References are also searchable alongside bits and flows, so supporting knowledge stays easy to find.

### Putting it together

Teams use Floxar to document their processes as executable workflows and then actually run them. Authors create bits and connect them into flows; people execute those flows, producing trails; references supply the background knowledge each step relies on. Because every run is recorded as a trail, you get consistency while the work happens and a reliable execution history afterwards — who did what, which path they took, what they entered, and how long it took.

*Last reviewed: 2026-07-28*

---

## Authoring craft

Knowing how the editor works is half of authoring; these articles cover what makes the content itself good. You learn how to give a flow one clear trigger and an unambiguous end, how to write bits that lead with the action, and when knowledge belongs in a reference rather than in a step.

### [What makes a good flow](/craft/what-makes-a-good-flow/)

A flow is a sequence of connected bits that leads someone to a defined outcome — a reusable template for a piece of work. Each time a person runs it, Floxar records their journey as a trail. A good flow is a repeatable, practical path: clear about when to start it, what "done" looks like, and every decision in between, yet simple enough to follow under pressure and to update as the process changes.

### [Writing effective bits](/craft/writing-effective-bits/)

A bit is the smallest unit of a flow: the text and interactive elements that tell the person on a step what to do right now. The best bits are just-in-time — they carry exactly the instruction needed to act at this step, and leave stable background knowledge to a linked reference.

### [Using references well](/craft/using-references-well/)

A reference is read-only supporting knowledge a person may consult during a step — policy, definitions, limits, matrices, rationale. If the bit is the just-in-time instruction, the reference is its just-in-case companion: helpful when the reader wants depth, never required to finish the step.

---

## Using references well

A reference is read-only supporting knowledge a person may consult during a step — policy, definitions, limits, matrices, rationale. If the bit is the just-in-time instruction, the reference is its just-in-case companion: helpful when the reader wants depth, never required to finish the step.

### What belongs in a reference — and what doesn't

The boundary is one question asked at each layer. Does the content tell the reader what to do at a step? That is a bit. Does the answer determine the next step? That is a branch in the flow. Is it stable, declarative knowledge the reader may consult but does not need in order to act? That is a reference. And if the reader must read it in full before the step makes sense, it belongs inline in the bit — not in a reference.

When in doubt, default to putting content in the bit. The cost of a missed reference is a quality nit; the cost of required information hidden in a reference is a wrong outcome.

### Keep every reference optional

The test: if removing the reference would make the workflow incomplete or confusing, that content belongs in the bit. A reference opens on top of the step, and nothing forces the reader to open it — so a step must be completable, correctly, by someone who never does. Keep the minimum decision rule in the bit itself and link the reference for the full policy, the rationale, and the edge cases.

### Don't disguise procedures as references

A reference states a rule, policy, definition, limit, or rationale — it never tells the reader what action to take next. Step-by-step instructions dressed up as a reference are really bits and should become bits. References are read-only by design and cannot contain interactive elements: they hold knowledge, they do not capture input or track actions.

### Give it a clean, specific title

A reference should form one coherent, bounded object with a specific title — "Refund Eligibility Policy", not "Misc Notes". If the best title you can find is vague, that is the signal to split the content into smaller pieces or not create the reference at all. Promoting a leftover grab-bag section to a reference just moves the mess somewhere with more authority.

### Keep it authoritative and current

Build references from official, accepted, current source material — not draft notes or stale examples. A published reference lends whatever it contains an air of authority, so unverified or outdated content does more damage there than it would anywhere else. When the underlying policy or knowledge changes, update the reference: the edit shows up immediately in every bit that links it.

### Maintain once, use everywhere

One reference can be linked from many bits across many flows, and a change to it propagates to all of them at once. That is the payoff of the split: a policy update becomes a one-place edit instead of a workflow redesign. Two habits protect it:

- Before creating a new reference, check whether an existing library entry already owns that knowledge. If it does, link it — a second copy will drift from the first.
- It is fine to create a reference before anything links to it; a library item awaiting use is valid.

### Choose the scope deliberately

Create a reference at the broadest scope where its knowledge is true — account-wide by default, and at an organization or group only when the knowledge is genuinely local to it. Scope is fixed at creation: a reference created at the wrong scope cannot be re-scoped and has to be recreated. Getting this right the first time keeps the reference usable everywhere it applies.

A good bit cites a good reference only where deeper detail helps, and never where it is required. Hold to that line and your references stay what they should be: a trustworthy layer of depth behind every step, not a place where critical instructions go missing.

*Last reviewed: 2026-07-28*

---

## What makes a good flow

A flow is a sequence of connected bits that leads someone to a defined outcome — a reusable template for a piece of work. Each time a person runs it, Floxar records their journey as a trail. A good flow is a repeatable, practical path: clear about when to start it, what "done" looks like, and every decision in between, yet simple enough to follow under pressure and to update as the process changes.

### Put decisions inside bits, not in the connections

Floxar does not execute a flow for you. Whoever runs it — a person or an agent — reads each bit, decides what applies, and picks one of the outgoing connections. Connections themselves carry no conditions or logic; they are only paths. Every decision therefore has to be spelled out in the bit where it happens: the question being asked, the criteria for each answer, and which path matches which answer. If a reader has to guess which way to go, that is not a style problem — it is how work goes wrong.

### Give the flow one clear trigger

From the title and description alone, a reader should be able to tell when this flow should be started and what situation it handles. A flow answers one process need, not several. If one flow tries to cover multiple unrelated triggers, split it into separate flows — each with a name that says what it is for.

### Make "done" unambiguous

A good flow has an explicit end: one or more final steps that represent the goal being achieved. Someone running the flow should always know whether the work is complete. A step with no way forward should exist only because the work is finished there — never by accident.

### Sequence steps the way the work happens

Order bits the way the work is actually done. The starting bit should lead onward, every bit should be reachable from the start, and there should be no stranded steps that nothing connects to. A single straight line can still hide problems: if the reader has to make uncaptured judgment calls between steps, those are missing decision points, not smooth sequence.

### Make handoffs explicit

Wherever execution passes between people, teams, or from a person to an agent, make the handoff a deliberate, named step: who takes over, and what condition must be met to proceed. Mentioning another team in passing does not count. For example, if legal must sign off before publishing, add a step that routes the work to legal — do not assume the reader knows to involve them.

### Branch only on real decisions

A branch should represent a genuine choice, with the decision criteria stated in the bit where the choice is made — one decision per branching point. If a bit asks more than one question, split it. Avoid fake branches (multiple paths that are not a real choice, or a "decision" whose criteria are never stated). And where a step needs data captured, include the right interactive element; where it produces something, say what and where — the reader should never guess what to record.

### Make repetition explicit

If the process retries, polls, or loops back for rework, represent that deliberately. Either connect back to the step being repeated — a step can even connect back to itself for retry patterns — or, where a connection cannot express it, state the repeat-until, retry, or escalation condition in the bit itself. Never flatten a repeating process into a one-way path and leave the reader to infer when to go back.

### Keep the right altitude

A flow is a template, not an essay. Each bit should be one focused unit of work: do not cram a whole workflow into one enormous bit, and do not fragment trivial steps into bits of their own. Structure at this altitude keeps the flow adaptable — when the process changes, the fix should be a localized edit to one bit or one branch, not a redesign.

Most of these criteria are craft: falling short makes a flow weaker, not invalid. The exceptions are unstated branch criteria and missing required inputs — those can send someone down the wrong path while everything looks fine, so fix them first.

*Last reviewed: 2026-09-23*

---

## Writing effective bits

A bit is the smallest unit of a flow: the text and interactive elements that tell the person on a step what to do right now. The best bits are just-in-time — they carry exactly the instruction needed to act at this step, and leave stable background knowledge to a linked reference.

### Give each bit one job — and let the title name it

A bit should accomplish one step, and its title should name that step. A useful test: if you need "and" to describe what the bit does, it is probably two bits. Bits that bundle several steps or several decisions become hard to follow and hard to maintain — split them.

### Lead with the action

The first line should say what to do. Context, if the step needs any, comes after the action — it must never bury it. The classic failure is a wall of text with the actual instruction somewhere in the middle; the reader should not have to excavate the step.

### Keep it as short as the step allows

A bit should be as short as its step permits and contain one focused unit of work. Dense content — code, tables, evidence, required examples — is fine when it belongs to the current step. Length becomes a problem when a bit combines unrelated actions, separate decisions, or background and policy material that should be split into other bits or linked as a reference. If you have set a meaningful target completion time on the bit, use it as a sanity check on size; if you have not, treat time targets as a hint for review rather than a rule.

### Make it self-sufficient — without becoming a policy manual

Someone competent in the domain should be able to complete the step from the bit alone. Keep the minimum instruction to act in the bit; put deeper policy, full tables, and rationale in a linked reference. Two failure modes sit on either side of this line:

- Restating a policy inline instead of linking the reference that owns it — the two copies drift apart over time.
- Pushing information the reader *must* have into a reference — the step can then be completed wrong without ever opening it. This is the one bit-writing mistake that causes wrong outcomes, not just rough edges.

The fix for both is the same split: state the minimum decision rule in the bit (for example, "Approve only when the purchase is within the allowed window and condition requirements are met") and link the reference for the full policy and its edge cases.

### Ask one question per branch point

If a bit gates progress on a choice, it should ask exactly one question, state the criteria for answering it, and its outgoing connections should map cleanly to the answers. A bit that asks two questions at one branching point forces the reader to untangle them — split it into two decision steps.

### Write to be scanned

Name the thing being acted on — say what to click or open, not "click here". Use lists for sequential steps and for parallel options; keep paragraphs short and reserve them for context that genuinely does not fit a list. People run flows mid-task, often under pressure; a scannable bit respects that.

### Add interactive elements only where they earn their place

Include an interactive element only where input is genuinely captured or an action is genuinely tracked — never as decoration. An element that captures nothing and tracks nothing just adds noise to the step and to the trail record. Give each element a clear name that is unique within the bit, so the answers recorded against it are unambiguous.

Most of these criteria are graded, not gated: a bit that falls short still saves and runs, and the shortfall is content debt to improve. The exception noted above — step-critical information hidden in a reference — is a correctness problem, because the step can be finished wrong while looking finished.

*Last reviewed: 2026-07-28*

---

## Account settings and administration

Account administrators keep a Floxar account organized: they shape its structure, manage its people, and set account-wide options. This article gives a conceptual overview of what account administration covers. You need the Admin permission level on the account to do these things.

### How an account is structured

Your account is your company's own space in Floxar. Inside it, you can organize work on two optional levels:

- **Organizations** — major divisions, such as departments, business units, or regions.
- **Groups** — teams inside an organization, such as a project team or workgroup.

Every flow and bit lives in exactly one place: in a specific organization or group, or at the account level. Content is not shared or inherited between organizations and groups — it stays where it was created, and it is available to the people whose permissions cover that place.

### Managing organizations and groups

From the account administration pages, administrators manage the structure as a tree:

- **Create** organizations, and groups inside them. A group always belongs to an organization, so at least one organization must exist before groups can be created.
- **Rename** an organization or group at any time.
- **Archive** an organization or group that is no longer needed. Archiving an organization also archives every group inside it. Archived items can be restored later.

Names must be unique among neighbours: two organizations in the same account cannot share a name, and neither can two groups under the same organization.

Archiving a place does not remove anyone from the account — people keep their account membership even when an organization or group they were assigned to is archived.

### Managing people

The account's user management page lists everyone in the account with their account-level role and status. From there, administrators can invite new people, change roles, assign people to organizations and groups, and deactivate or reactivate them. A reactivated person returns with basic membership only, so any roles they previously held must be granted again.

The companion article on inviting users, roles, and permissions covers this in detail, including how permissions inherit downward from the account through organizations to groups.

### Account-level settings

Administrators control a small set of account-wide options:

- **Whether organizations and groups can be created.** Separate settings gate each level of the structure, so you can keep an account flat if you prefer.
- **Flow review.** An optional review step for flows. When enabled, new flows start as drafts and go through review, where someone with Admin or Edit access approves or rejects them. When the setting is off (the default), new flows are approved immediately.

Settings defined at the account level apply across all organizations and groups, unless a specific organization or group has its own value for a setting that supports one.

### The working context

People who belong to several organizations or groups choose which one they are currently working in using a context switcher in the navigation. Places where a person holds only basic membership are not offered as choices, since there is nothing they can do there. If someone's access to their selected place is removed, Floxar falls back to the account level rather than leaving them stuck.

As an administrator, keep the structure aligned with how your teams actually work: grant roles at the level that matches each person's responsibilities, and let inheritance handle the rest.

*Last reviewed: 2026-07-28*

---

## Building flows

A flow is a navigable sequence of connected bits — the template for a process that people run step by step. You build a flow by choosing where it starts and connecting bits into paths, including branching paths where the person's choice determines what comes next. This article covers flow setup, connections, how navigation works for the person running the flow, and the editing rules that keep flows consistent.

### Setting up a flow

A flow needs a title and a starting bit before it can be saved. A description is optional but worth writing — it gives people context and makes the flow easier to find in search. You can add category tags to organize and filter flows, and set a default priority (low, medium, high, or critical); each run inherits that priority, and it can be changed on the individual run.

### The start bit

Every flow has exactly one starting bit — the entry point where every run begins. Because an active flow must keep a valid entry point, the start bit cannot be archived while the flow is active, and you cannot simply remove it from an active flow — replace it with another bit, or deactivate the flow instead. If a flow has more than one bit, its start bit should have at least one outgoing connection.

### Connecting bits into paths

Connections are one-way links from one bit to another. Each outgoing connection appears as a navigation option inside the source bit when the flow runs, so giving a bit several outgoing connections is how you create branching paths.

Connections carry no logic or conditions of their own — the person running the flow chooses which option to take. Put the decision criteria in the bit's content ("If the customer is eligible, continue to approval; otherwise, choose the escalation path") so the choice is clear at the moment it is made.

Paths can loop: a route may return to an earlier bit, and a bit may even connect back to itself, which is useful for retry or repeat-until-done steps. The same pair of bits can also be connected more than once when two distinct options should lead to the same next step. A bit other than the start bit that has no connections cannot be reached when the flow runs, so make sure every step is wired into the flow.

### How navigation works for the person running it

Someone running your flow starts at the start bit. At each step they read the bit's content, complete any interactive elements, and pick one of the navigation options to move to the next bit. Every visit is recorded in their trail, in order, including repeat visits to the same bit.

### Editing rules and consistency

- **Editing and deactivating require edit permission.** People with lower permission levels do not see those actions.
- **Flows are never deleted.** To retire a flow you deactivate it instead, which takes it out of use while preserving its history and every trail that ran through it.
- **Bits are independent of flows.** Editing a bit's content changes it everywhere the bit is used, and does not alter any flow's review status.
- **Archiving a bit removes its connections from every flow**, so check the flows that used it and rewire their paths if needed.
- **An optional review step can be enabled for your account.** When it is on, new flows start as drafts, can be submitted for review, and are approved or rejected by a reviewer with sufficient permission. Editing a flow that is rejected or waiting for review returns it to draft, so the reviewer always assesses a clean revision. Once a flow is approved, it stays approved through later edits. When the review setting is off, flows are approved from the moment they are created.

*Last reviewed: 2026-09-23*

---

## Creating and editing bits

Bits are the smallest building blocks of content in Floxar. Each bit is a single, self-contained process step that combines rich text, media, and interactive elements that can capture input from the person working through it. This article covers what a bit contains, what the editor can do, and how bits relate to flows.

### What a bit contains

Every bit has a title, and you must provide one before the bit can be created. You can also add a description, an abstract, and category tags — categories such as "Onboarding" or "Troubleshooting" help you filter, group, and find related content. A bit can carry a target completion time (up to one hour) so you can see whether a step tends to take longer than intended. Reading statistics such as reading time and word count are computed automatically from the content; you never maintain them yourself.

The body of a bit is a structured document: the title always sits at the top and cannot be deleted, and the document always ends with a text line so there is always somewhere to keep typing.

### Writing and formatting content

The rich-text editor supports the content types you would expect from a modern document editor:

- **Text** — paragraphs, several levels of headings, formatting such as bold and italics, quotes, and highlighted callouts for important notes.
- **Lists** — numbered lists, bulleted lists, and definition lists for term-and-definition pairs.
- **Tables** — with optional header, footer, and caption.
- **Code blocks** — for technical steps and snippets.
- **Media** — images (optionally with captions) and videos, either uploaded or referenced from an external address. A bit can hold up to 25 media files; images are compressed automatically on upload.
- **Other blocks** — embedded frames that show external web content inside a step, link preview cards, and dividers that separate sections.

Your changes are saved automatically after a short pause in editing, so you do not need to save each edit by hand. Structured blocks such as tables, media, and interactive elements are configured through their own panels and menus rather than edited as free text.

### Interactive elements

Interactive elements are the parts of a bit that capture data or record an action while someone runs the bit inside a trail. Nine types are available:

- **Checklist** — a list of items the person ticks off; each item records its own checked state.
- **Date picker** — captures a date, a time, or a date and time, depending on how you configure it.
- **Dropdown** — a single choice from a configured list of options.
- **Radio buttons** — a single choice from a set of options shown all at once.
- **Text area** — free-form text such as notes or case details. You can control its size and maximum length, and add a validation pattern that either warns about non-matching input or blocks it.
- **Searchable field** — lets the person search a configured data source and select one or more matching items.
- **Inline link** — a link inside a sentence that records whether it was opened.
- **Link card** — a link presented as a preview card with details about the destination; it also records whether it was opened.
- **Video** — a video that records whether it was played.

Each element carries a short name that identifies its captured answer in trail records; names are generated automatically and you can rename them. The answers people enter are saved step by step with their trail — see the article on running and tracking trails.

### How bits relate to flows

Bits are library content, not parts of any single flow. A bit exists on its own and can appear in zero, one, or many flows. You build a flow by connecting bits: connections appear as navigation buttons inside the bit, and each one leads to another step. Removing a bit from one flow does not remove it from the library or from other flows that use it.

Bits are never deleted. To retire one, you archive it: archiving removes the bit from every flow's paths and prevents it from being added to new flows, while past trail records that visited it remain fully readable. A bit that is the starting bit of an active flow cannot be archived — point the flow at a different start or deactivate the flow first.

*Last reviewed: 2026-07-28*

---

## How-to

These articles walk you through the everyday tasks in Floxar, from signing in to building content and running it. You learn how to create bits, connect them into flows, run and track trails, and work with references in the process library. If you administer an account, you also find how to invite people, grant roles and manage account settings.

### [Signing in and authentication](/how-to/signing-in-and-authentication/)

You use Floxar with a personal Floxar sign-in tied to your email address. This article covers signing in, verifying your email as a new user, what to do when you cannot sign in, and how sessions behave.

### [Creating and editing bits](/how-to/creating-and-editing-bits/)

Bits are the smallest building blocks of content in Floxar. Each bit is a single, self-contained process step that combines rich text, media, and interactive elements that can capture input from the person working through it. This article covers what a bit contains, what the editor can do, and how bits relate to flows.

### [Building flows](/how-to/building-flows/)

A flow is a navigable sequence of connected bits — the template for a process that people run step by step. You build a flow by choosing where it starts and connecting bits into paths, including branching paths where the person's choice determines what comes next. This article covers flow setup, connections, how navigation works for the person running the flow, and the editing rules that keep flows consistent.

### [Running and tracking trails](/how-to/running-and-tracking-trails/)

A trail is the record of one run through a flow: which steps were visited, in what order, what was entered at each step, and what happened to the run along the way. When you start a flow, Floxar creates a trail for you and keeps it as a complete, reviewable history of that piece of work. This article covers starting a trail, moving through it, how your answers are saved, and what the finished record contains.

### [References and the process library](/how-to/references-and-the-process-library/)

A reference is a read-only supporting document — a policy, guideline, definition, FAQ, or decision matrix that people may need to consult while working through a flow. Where a bit tells you what to do, a reference holds the why, the what-if, and the background. This article covers what references are for, how they support bits and flows, and how the process library and search surface them.

### [Inviting users, roles, and permissions](/how-to/inviting-users-roles-and-permissions/)

Every person in a Floxar account has a permission level that controls what they can see and do. This article explains what each level means, how new people join an account, and how access flows through the account's organizations and groups.

### [Account settings and administration](/how-to/account-settings-and-administration/)

Account administrators keep a Floxar account organized: they shape its structure, manage its people, and set account-wide options. This article gives a conceptual overview of what account administration covers. You need the Admin permission level on the account to do these things.

---

## Inviting users, roles, and permissions

Every person in a Floxar account has a permission level that controls what they can see and do. This article explains what each level means, how new people join an account, and how access flows through the account's organizations and groups.

### Permission levels

Floxar uses four permission levels, plus a basic membership status:

- **Admin** — Full management of the account: account settings, user administration, and full access to all content.
- **Edit** — Create and change content, including flows and bits.
- **Engage** — Use content: start and work through flows, filling in the interactive elements (forms, checklists, and similar) along the way.
- **View** — Read-only access: see content without changing or running it.
- **Member** — Belonging without access. A Member appears in the account's user list but cannot see or do anything until a role is granted. This status is normal for people whose real role is granted on a specific organization or group, and for people who were just added and are waiting for a role.

A higher level always includes the abilities of the levels below it — anyone with Edit, for example, can also do everything Engage and View allow.

### Inviting someone to your account

Administrators bring new people in by invitation:

1. An administrator creates an invitation with the person's email address and a permission level — Admin, Edit, Engage, or View. If no level is chosen, View is used. The invitation can also target a specific organization or group, so the person's access starts exactly where it should.
2. The person receives an invitation email with a link.
3. When they create their Floxar sign-in using the same email address the invitation was sent to, they join the account automatically with the assigned access — no extra approval step.

While an invitation is still pending, administrators can resend it or revoke it. Once accepted, an invitation can no longer be revoked; manage the person's access directly instead.

Administrators can also add someone before that person has ever signed in, by entering their email address in the account's user management area. When the person later creates their Floxar sign-in with the same address, their access is already in place.

### Where a role applies

An account can contain organizations (major divisions such as departments), and each organization can contain groups (teams). A permission level can be granted at any of these levels:

- on the whole account,
- on one organization,
- or on one group.

Administrators assign people to organizations and groups, and set their role there, from the account administration pages.

### Permission inheritance

Permissions flow downward. A role granted on the account applies to every organization and group inside it, and a role granted on an organization applies to every group inside that organization.

Grants only ever add access:

- When several grants apply to the same place, the most permissive one wins.
- You cannot reduce inherited access by granting a lower level further down. Someone with Edit on the whole account keeps Edit everywhere, even if they are also given View on one group.

A common pattern: a person is a Member at the account level and has Edit on a single group. They can work only inside that group — and the account's user list shows them as "Member", because that is their account-level status.

### Changing and removing access

Administrators can change a person's role or deactivate them from the account's user management area. Deactivating removes access but preserves everything the person created. If they are reactivated later, they return with basic membership only — any roles they previously held must be granted again.

You cannot change your own role, deactivate yourself, or remove yourself from the account; another administrator has to make those changes. This protects accounts from accidental lockouts.

Finally, a person can belong to more than one Floxar account, with different permission levels in each. Access and content never carry over between accounts.

*Last reviewed: 2026-07-28*

---

## References and the process library

A reference is a read-only supporting document — a policy, guideline, definition, FAQ, or decision matrix that people may need to consult while working through a flow. Where a bit tells you what to do, a reference holds the why, the what-if, and the background. This article covers what references are for, how they support bits and flows, and how the process library and search surface them.

### What references are for

References hold stable, declarative knowledge: eligibility rules, policy detail, specifications, escalation criteria, and similar material that supports a step without driving it. A good rule of thumb when authoring: if removing the content would make the workflow incomplete or confusing, it belongs in the bit itself; if it is deeper detail someone might consult, it belongs in a reference.

References are written with the same rich-content editing experience as bits — headings, formatted text, lists, tables, images, videos, and links — but they never contain interactive input elements. They are for reading, not for capturing data. Each reference has a title, an optional summary that appears in search previews, and category tags for filtering.

### How references support bits and flows

References live in the library independently of any bit. A reference can be linked to many bits, and a bit can cite many references; a reference with no links yet is still a valid library item awaiting use. Content is never copied into a bit — the bit always shows the reference's current content, so an edit to a reference is immediately live everywhere it is linked.

While someone runs a flow, a bit's linked references are available from within the step and open in an overlay, so the person consults the material without leaving their place in the flow. Authors can also cite a reference at the exact point in a bit's text where it is relevant.

A reference belongs either to the whole account or to a specific organization or group, and it can only be attached to bits in that same scope. The scope is chosen when the reference is created and cannot be changed afterward, so create a reference at the broadest level where the knowledge applies — account-wide unless it is genuinely local to one team.

### Managing content in the process library

The process library is the browse-and-manage home for your account's content, with sections for references, bits, and flows. You can search within it, filter by category, author, and dates, sort the list, and — with edit permission — switch to a view of archived content. Creating and editing references requires edit permission; anyone with view access can read them.

Each reference shows where it is used: the list of bits that link to it. That usage view matters when retiring content, because a reference cannot be archived while any bit still links to it — unlink it everywhere first. Archiving is one-way: it hides the reference from the library and from readers, and it cannot be undone from the product. If a reference a bit pointed to becomes unavailable, the bit shows a placeholder message in its place rather than broken content.

### Finding references through search

Search works across flows, bits, and references from one place. Reference results show the summary and which bits use the reference, so you can judge relevance and see the context it supports before opening it. Category tags narrow results the same way they do in the library. Search is the quick term-based lookup; the process library is the browsing and administration view of the same content.

*Last reviewed: 2026-07-28*

---

## Running and tracking trails

A trail is the record of one run through a flow: which steps were visited, in what order, what was entered at each step, and what happened to the run along the way. When you start a flow, Floxar creates a trail for you and keeps it as a complete, reviewable history of that piece of work. This article covers starting a trail, moving through it, how your answers are saved, and what the finished record contains.

### Starting a trail

Starting a flow creates a new trail assigned to you, beginning at the flow's starting bit. A trail can be named so it is easy to find later in lists and search, and it carries a priority (low, medium, high, or critical) that can be adjusted on the trail itself.

You work one trail at a time: if you start or resume a trail while another of yours is active, the previous one is automatically paused. Nothing is lost — the paused trail keeps its place and can be resumed whenever you are ready.

### Moving through the flow

Floxar does not decide your path for you. At each step you read the bit's content, complete its interactive elements, and choose one of the navigation options shown in the bit to move on. Every bit you visit is recorded as a numbered step in your trail, and revisiting a bit — for example, in a retry loop — simply adds another step.

### How your answers are captured and saved

The interactive elements in a bit — checklists, dropdowns, radio buttons, date pickers, text areas, searchable fields, and tracked links and videos — capture your input as you work. Answers are saved automatically a few seconds after you enter them; you do not submit a form or save manually.

Answers belong to the step where you entered them. If you revisit the same bit later in the trail, that new visit records its own set of answers, so the history shows what was entered at each point in time. If a trail is not active or is not assigned to you, its elements are shown read-only.

### Pausing, handing off, and queueing

- **Pause** a trail to set it aside; it keeps its assignee and its place, and you can resume it later.
- **Transfer** a trail to hand it to a colleague. It lands on their worklist, and they start it themselves when ready — a handoff never interrupts what the recipient is doing. Every transfer is logged with who handed it off, who received it, when, and an optional reason.
- **Release to the queue** to put a trail back in the shared pool with no assignee. Teammates with access can claim it onto their own worklist and then start it.

### Completing a trail

When the work is done, mark the trail completed; if it is stopped without finishing, mark it abandoned. Both states are final: the trail becomes read-only and serves as the permanent record of the run. If standard closing reasons have been configured for the flow, you pick one when closing and can add a free-text note.

A completed or abandoned trail can be reopened, but a reason is required and is recorded alongside the original closing event — the history is never rewritten.

### What a trail records for later review

Every trail keeps:

- **The full path** — every bit visited, in order, with timestamps for each step.
- **Every answer** — the values captured by each interactive element at each step.
- **Status history** — every status change, with who made it, when, and why.
- **Handoff history** — every transfer between people, including releases to and claims from the queue.
- **Time measures** — how long the trail has been open, how much of that was active working time, and how long it sat paused or waiting after a handoff.

Interested parties are notified when a trail is completed or transferred. Because closed trails are preserved rather than deleted — even if the underlying content is later archived — they remain a reliable base for review, audit, and analytics.

*Last reviewed: 2026-07-28*

---

## Signing in and authentication

You use Floxar with a personal Floxar sign-in tied to your email address. This article covers signing in, verifying your email as a new user, what to do when you cannot sign in, and how sessions behave.

### Signing in

Open Floxar in your browser. If you are not already signed in, you are taken to the sign-in screen; enter your Floxar sign-in details there. Once signed in, you land in your account and can pick up where you left off.

If you belong to more than one Floxar account, signing in opens your default account. You can switch to another of your accounts from your profile page.

### Creating your sign-in for the first time

New users create their Floxar sign-in from the same screen. What happens next depends on how you arrived:

- **You were invited.** Create your sign-in with the exact email address the invitation was sent to. You will land directly in the inviting account with the access your administrator assigned — there is no extra approval step.
- **You signed up on your own.** Floxar creates a brand-new account for you, and you are its administrator from the start.

As a new user, you are asked to verify your email address. You can start using Floxar right away, before verifying — but some usage limits are tighter until your email address is confirmed, so it is worth completing verification early.

If many sign-ups are attempted from the same network in a short time, further attempts may be blocked temporarily. Wait a while and try again.

### When you cannot sign in

- **Forgotten password.** Start the password reset from the sign-in screen — it offers a recovery path for exactly this situation. Follow the steps it presents to set a new password, then sign in normally.
- **A temporary error during sign-in.** Occasionally sign-in fails with a message saying it is temporarily unavailable. Nothing is wrong with your account — simply try again.
- **You can sign in but no longer see your account.** Your membership in that account may have been deactivated by an administrator. Contact an administrator of that account; only they can restore your access. If you are reactivated, you return with basic membership, and any roles you previously held must be granted again.

Keep in mind that your sign-in and your account access are separate things: signing in proves who you are, while what you can see and do inside each account is controlled by the roles granted to you there.

### Sessions and signing out

Once signed in, you stay signed in while you work. For security, sessions do not last forever: after enough time has passed, you will be asked to sign in again.

Changes to your access apply immediately, not at your next sign-in. If an administrator changes your role or deactivates your membership, the change takes effect on your very next action in Floxar.

You can sign out at any time. Signing out ends your session in that browser; sign in again whenever you want to continue.

*Last reviewed: 2026-07-28*

---

## Agents and AI clients: which one you need

There are two ways to reach Floxar's MCP tools: a person connects an AI client they use, or an account admin registers an agent that acts on its own. Both reach the same account URL, `https://mcp.floxar.com/a/<account_id>`, and the same tools, and both are limited by a role. The rest differs.

### When to use which

- **Connect an AI client** when you want to work in Floxar yourself from an AI app such as Claude, ChatGPT or Cursor. You sign in from the app with your own login, and everything the app does is recorded as yours. You need no registration. See [Connecting an AI client](/integrations/connecting-an-ai-client/).
- **Register an agent** when software acts on its own, under an identity of its own: an AI worker, an integration or a scheduled job that runs without a person signing in. See [Registering an agent](/integrations/registering-an-agent/).

If you are unsure, ask who should be accountable for the work in the audit trail. If it is you, connect a client. If it is the software, register an agent.

### How they differ

| What differs | A person's AI client | An agent |
| --- | --- | --- |
| Who acts | The person, through the client | The agent, under its own identity |
| How it gets in | Sign-in in a browser, then consent | Client ID and secret, exchanged for a token at `tokens.floxar.com` |
| Set up by | The person, in their client | An account admin, in the Agent Registry |
| What limits it | The person's role, narrowed by what the person allowed and what the account lets clients have | The agent's role, and the level of its organization or group assignments inside them |
| Account switch | MCP connections must be on for the account | None; the registration is the switch |
| Staying connected | Renews on its own; signs in again after 7 days unused or 30 days | Requests a new token before each hour is up |
| Ending it | The person disconnects their applications from their profile's Security page, or an admin revokes the connection under MCP Connections | An admin rotates, deactivates or deletes the agent |
| Recorded as | The person, marked as made through MCP with the client's name | The agent, marked as made through MCP |

### What stays the same

- **The URL.** One account URL per account, for both. A connection or a token for one account's URL does not work at another's.
- **The tools and the checks.** The same tools, and the same permission checks on every call. Neither a client nor an agent gets more than its role allows, and a tool the role does not allow answers `PERMISSION_DENIED`.
- **The audit trail.** Every change made through MCP is recorded as made through MCP, under whoever made it.

*Last reviewed: 2026-09-30*

---

## Connect ChatGPT to Floxar

ChatGPT connects to Floxar in developer mode, which is available on ChatGPT Pro, Plus, Business, Enterprise and Education accounts on the web; a workspace's policy can restrict it. ChatGPT identifies itself to Floxar with its own Client ID Metadata Document, so you enter no client ID or secret. Reading and running trails through ChatGPT are confirmed.

Before you start, make sure MCP is on for your account and have your account URL ready. [Connecting an AI client](/integrations/connecting-an-ai-client/) explains both, and what the sign-in and consent page show.

### Add Floxar

1. In ChatGPT, open Settings, then Security and login, and turn on Developer mode.
2. Open ChatGPT's plugins page (`chatgpt.com/plugins`) and select the plus button.
3. Give it a name for the account, such as `acme-floxar`, add a description, and paste your account URL as the MCP server URL. Then create the connection.
4. Follow the prompt to sign in to Floxar in the browser window, confirm the account and allow the connection.
5. In a new conversation, add the connection from the tools menu.

The MCP server URL is your account URL:

```text
https://mcp.floxar.com/a/<account_id>
```

### What the sign-in looks like

The consent page shows ChatGPT under Floxar's label for it. ChatGPT asks for the three capabilities and to stay connected; the consent page lists what the account allows of that.

### Known limits

- **A revoked connection looks like a tool error.** When an account admin revokes the connection, ChatGPT reports "an internal tool error" and offers no reconnect. Use Reconnect in the plugin's settings to connect again.
- **Uninstalling the plugin is local only.** The connection stays active in Floxar until you or an account admin end it there (see "Disconnecting and revoking" in [Connecting an AI client](/integrations/connecting-an-ai-client/)).
- **Codex may share this connection.** If you also use Codex with the same account, Codex may route its calls through this ChatGPT connection, and revoking it disconnects both. See [Connect Codex](/integrations/connect-codex/).

*Last reviewed: 2026-09-30*

---

## Connect Claude Code to Floxar

You add Floxar to Claude Code with one command in your terminal. Claude Code identifies itself to Floxar with its own Client ID Metadata Document, so you enter no client ID or secret.

Before you start, make sure MCP is on for your account and have your account URL ready. [Connecting an AI client](/integrations/connecting-an-ai-client/) explains both, and what the sign-in and consent page show.

### Add Floxar

1. Add the server from your terminal. Append `--scope user` to make it available in every project.

   ```bash
   claude mcp add --transport http acme-floxar https://mcp.floxar.com/a/<account_id>
   ```

2. Start Claude Code, run `/mcp`, select `acme-floxar` and choose Authenticate. Your browser opens so you can sign in to Floxar, confirm the account and allow the connection. You can also run `claude mcp login acme-floxar` from an interactive terminal.
3. Run `/mcp` again: the server shows as connected and its tools are ready.

### What the sign-in looks like

The consent page shows Claude Code under Floxar's label for it. Claude Code asks for every capability, and to stay connected, each time it connects; the consent page lists what the account allows of that.

### Known limits

- **`claude mcp login` needs an interactive terminal.** Run it where you can type, or authenticate from `/mcp` inside Claude Code.
- **`claude mcp logout` is local only.** It clears Claude Code's stored sign-in, but the connection stays active in Floxar until you or an account admin end it there (see "Disconnecting and revoking" in [Connecting an AI client](/integrations/connecting-an-ai-client/)).
- **Adding access later means reconnecting.** A read-only connection never sees a write tool, so Claude Code cannot widen it by itself. Once the account allows more, sign in again:

  ```bash
  claude mcp logout acme-floxar
  claude mcp login acme-floxar
  ```

- **More than one account.** Each account needs its own server name, for example `acme-floxar` and `globex-floxar`; Claude Code refuses a duplicate name.

*Last reviewed: 2026-09-30*

---

## Connect Claude (claude.ai and Claude Desktop) to Floxar

claude.ai and Claude Desktop share the same connectors, so you add Floxar once as a custom connector and use it in both. Claude identifies itself to Floxar with its own Client ID Metadata Document: you enter no client ID or secret. Reading, running trails and authoring through Claude are confirmed.

Before you start, make sure MCP is on for your account and have your account URL ready. [Connecting an AI client](/integrations/connecting-an-ai-client/) explains both, and what the sign-in and consent page show.

### Add Floxar

1. In Claude, open Settings, then Connectors, and select Add custom connector.
2. Give it a name for the account, such as `acme-floxar`, paste your account URL, and select Add.
3. Select Connect. Sign in to Floxar in the browser window, confirm the account and allow the connection.
4. In a chat, open the tools menu and make sure the Floxar connector is turned on.

The remote MCP server URL is your account URL:

```text
https://mcp.floxar.com/a/<account_id>
```

### What the sign-in looks like

The consent page shows Claude under Floxar's label for it, with the domain it identifies itself with and where the connection returns to. Claude asks for every capability the account allows, and to stay connected; the consent page lists what the account leaves of that.

### Known limits

- **One connection covers both.** When claude.ai and Claude Desktop use the same connector, one sign-in covers both, and ending the connection in Floxar disconnects both.
- **Removing the connector in Claude revokes nothing in Floxar.** The connection stays active until you or an account admin end it in Floxar (see "Disconnecting and revoking" in [Connecting an AI client](/integrations/connecting-an-ai-client/)).
- **A mistyped URL** is reported by Claude as "Not found" when you add the connector.
- **After a connection is revoked in Floxar,** Claude may show "This connector has no tools available" until you disconnect and reconnect the connector.
- **Adding access later means reconnecting.** To give the connector more capabilities than it was first allowed, disconnect and reconnect it; the new consent lists what it gets.

*Last reviewed: 2026-09-30*

---

## Connect Codex to Floxar

The Codex command line, the Codex IDE extension and the ChatGPT desktop app share one configuration, so you add Floxar once. Codex identifies itself to Floxar with its own Client ID Metadata Document, so you enter no client ID or secret.

Use Codex 0.151.0 or later; earlier releases do not present the identity Floxar recognises. Leave Codex's `oauth_resource` override unset.

Before you start, make sure MCP is on for your account and have your account URL ready. [Connecting an AI client](/integrations/connecting-an-ai-client/) explains both, and what the sign-in and consent page show.

### Add Floxar

1. Add the server from your terminal. Codex starts the sign-in at once and opens your browser.

   ```bash
   codex mcp add acme-floxar --url https://mcp.floxar.com/a/<account_id>
   ```

2. If the browser did not open, run `codex mcp login acme-floxar`. Sign in to Floxar, confirm the account and allow the connection.
3. In the ChatGPT desktop app, open Settings, then MCP servers, then Add server instead, choose Streamable HTTP and paste your account URL. Save it, select Restart, then Authenticate.

### What the sign-in looks like

The consent page shows Codex under Floxar's label for it. The command line runs on your computer, so the connection returns to a local address, and the consent page says so. Codex asks for the three capabilities and to stay connected.

### Known limits

- **Codex may use your ChatGPT connection.** If the same account is also a ChatGPT connector on your ChatGPT account, Codex may route its calls through that connector, and the two share one connection: revoking it disconnects both.
- **`codex mcp logout` is local only.** The connection stays active in Floxar until you or an account admin end it there (see "Disconnecting and revoking" in [Connecting an AI client](/integrations/connecting-an-ai-client/)).
- **After a revocation, the server may silently disappear** from a Codex session. Run `codex mcp login acme-floxar` to connect again.
- **Codex's own approval policy applies.** In non-interactive runs, Codex's approval setting can refuse write tools before they reach Floxar; that is a Codex setting, not a Floxar one.
- **Adding access later means reconnecting.** Run `codex mcp login acme-floxar` again; the new consent lists the capabilities the connection gets.

*Last reviewed: 2026-09-30*

---

## Connect Cursor to Floxar

Cursor's desktop application and command line share one `mcp.json`. Cursor publishes no metadata document, so it identifies itself with the identifier Floxar publishes for it, `cursor`. There is no client secret. The connection is confirmed with Cursor 3.22.12 (desktop).

Before you start, make sure MCP is on for your account and have your account URL ready. [Connecting an AI client](/integrations/connecting-an-ai-client/) explains both, and what the sign-in and consent page show.

### Add Floxar

1. Add the server to `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (this project). If the file already lists servers, add only the Floxar entry inside the existing `mcpServers` object. Keep the `auth` block as shown: `CLIENT_ID` is the identifier Floxar publishes for Cursor, and `scopes` are what Cursor asks to be allowed.

   ```json
   {
     "mcpServers": {
       "acme-floxar": {
         "url": "https://mcp.floxar.com/a/<account_id>",
         "auth": {
           "CLIENT_ID": "cursor",
           "scopes": ["floxar.read", "floxar.execute", "floxar.author", "offline_access"]
         }
       }
     }
   }
   ```

2. Start the server in Cursor. When it asks you to sign in, sign in to Floxar in the browser window, confirm the account and allow the connection. From the command line, run `agent mcp login acme-floxar`.

### What the sign-in looks like

The consent page shows Cursor under Floxar's label for it, with its vendor. Cursor runs on your computer, so the connection returns to a local address, and the consent page says so.

### Known limits

- **Type the identifier exactly.** A `CLIENT_ID` other than `cursor` is refused as an invalid client.
- **Disconnect in Cursor's MCP settings is local only.** The connection stays active in Floxar until you or an account admin end it there (see "Disconnecting and revoking" in [Connecting an AI client](/integrations/connecting-an-ai-client/)).
- **After a revocation,** Cursor reports that the call failed on authentication and offers to authenticate again; a fresh sign-in and consent restore the connection.

*Last reviewed: 2026-09-30*

---

## Connect Grok Build to Floxar

Grok Build, the command-line client, identifies itself with the identifier Floxar publishes for it, `grok-build`. There is no client secret. The connection is confirmed with Grok Build 1.0.44. Grok on grok.com is a separate client with a guide of its own: [Connect Grok (grok.com)](/integrations/connect-grok/).

Grok Build sends no scopes unless they are set. Without them, Floxar takes the request as asking for the three capability scopes, and the connection does not ask to stay connected, so the `oauth_scopes` line below is recommended.

Before you start, make sure MCP is on for your account and have your account URL ready. [Connecting an AI client](/integrations/connecting-an-ai-client/) explains both, and what the sign-in and consent page show.

### Add Floxar

1. Add the server to `~/.grok/config.toml` (or `.grok/config.toml` in a project).

   ```toml
   [mcp_servers.acme-floxar]
   url = "https://mcp.floxar.com/a/<account_id>"
   oauth_client_id = "grok-build"
   oauth_scopes = ["floxar.read", "floxar.execute", "floxar.author", "offline_access"]
   ```

2. Start Grok Build, run `/mcps` and press `i` to authenticate. Sign in to Floxar in the browser window, confirm the account and allow the connection.

### What the sign-in looks like

The consent page shows Grok Build under Floxar's label for it, with its vendor. Grok Build runs on your computer, so the connection returns to a local address, and the consent page says so.

### Known limits

- **Grok Build may share your grok.com connection.** If the same account is also a connector on your grok.com account, Grok Build offers that connection under `/mcps` as well, and the two then share one connection: revoking it disconnects both.
- **Disconnecting on grok.com is local only,** including for a connection Grok Build shares. The connection stays active in Floxar until you or an account admin end it there (see "Disconnecting and revoking" in [Connecting an AI client](/integrations/connecting-an-ai-client/)).
- **After a revocation,** Grok Build's log reports a failed handshake and a failed start. Authenticate again from `/mcps`.
- **Type the identifier exactly.** An `oauth_client_id` other than `grok-build` is refused as an invalid client.

*Last reviewed: 2026-09-30*

---

## Connect Grok (grok.com) to Floxar

You add Floxar to Grok on grok.com as a custom connector. Grok identifies itself with its own Client ID Metadata Document, so it needs no client ID or secret from you. Reading and running trails through Grok are confirmed. Grok Build, the command-line client, is a separate client with a guide of its own: [Connect Grok Build](/integrations/connect-grok-build/).

On Grok Business and Enterprise, a team admin provisions the connector in the cloud console first.

Before you start, make sure MCP is on for your account and have your account URL ready. [Connecting an AI client](/integrations/connecting-an-ai-client/) explains both, and what the sign-in and consent page show.

### Add Floxar

1. Open `grok.com/connectors`, select New Connector, then choose Custom.
2. Enter your account URL as the MCP server URL.
3. Sign in to Floxar in the window grok.com opens, confirm the account and allow the connection.

The MCP server URL is your account URL:

```text
https://mcp.floxar.com/a/<account_id>
```

### What the sign-in looks like

The consent page shows Grok under Floxar's label for it. Grok asks for the three capabilities and to stay connected; the consent page lists what the account allows of that.

### Known limits

- **A revoked connection asks you to authenticate.** After an account admin revokes the connection, Grok reports "Auth required". Use Re-Auth on the connector's page to connect again.
- **Disconnecting on grok.com is local only.** The connection stays active in Floxar until you or an account admin end it there (see "Disconnecting and revoking" in [Connecting an AI client](/integrations/connecting-an-ai-client/)).
- **Grok Build may share this connection.** Once the account is a grok.com connector, Grok Build can use the same connection, and revoking it disconnects both.

*Last reviewed: 2026-09-30*

---

## Connect VS Code to Floxar

You use Floxar in VS Code from GitHub Copilot Chat in agent mode. VS Code identifies itself to Floxar with its own Client ID Metadata Document, so you enter no client ID or secret. The connection is confirmed with VS Code 1.139, the desktop editor.

Before you start, make sure MCP is on for your account and have your account URL ready. [Connecting an AI client](/integrations/connecting-an-ai-client/) explains both, and what the sign-in and consent page show.

### Add Floxar

1. Add the server to `.vscode/mcp.json` in your workspace. If the file already lists servers, add only the Floxar entry inside the existing `servers` object. Or run MCP: Add Server from the Command Palette, choose HTTP, paste your account URL and give it a name for the account.

   ```json
   {
     "servers": {
       "acme-floxar": {
         "type": "http",
         "url": "https://mcp.floxar.com/a/<account_id>"
       }
     }
   }
   ```

2. Start the server. When VS Code asks to let Floxar sign in, allow it, then sign in to Floxar, confirm the account and allow the connection.
3. Open Copilot Chat in agent mode. Floxar's tools appear in the tools picker.

### What the sign-in looks like

The consent page shows VS Code under Floxar's label for it. VS Code runs on your computer, so the connection returns to a local address, and the consent page says so.

### Known limits

- **VS Code stays connected.** Floxar renews its access whether or not VS Code asks to stay connected, because its registration allows it.
- **Signing out in VS Code is local only.** It discards VS Code's access, but the connection stays active in Floxar until you or an account admin end it there (see "Disconnecting and revoking" in [Connecting an AI client](/integrations/connecting-an-ai-client/)).
- **The desktop editor only.** VS Code for the Web, in the browser, is not a supported way to connect and is expected to be refused.
- **More than one account.** Give each account's entry its own name; a second entry with the same name in `mcp.json` replaces the first.

*Last reviewed: 2026-09-30*

---

## Connecting an AI client to Floxar

Floxar has a Model Context Protocol (MCP) server, so you can work in Floxar from your own AI client: find and read your flows, steps, references and trails, run trails, and create or edit flows. You sign in with your usual Floxar login, and the client can only do what you approve and what your role in the account allows.

If Floxar's sign-in page sent you here, it also said why the connection stopped. Find its message under "If sign-in stops" at the end of this article.

This article covers what every client has in common. Each verified client has its own short guide with the exact steps:

- [Claude (claude.ai and Claude Desktop)](/integrations/connect-claude/)
- [Claude Code](/integrations/connect-claude-code/)
- [VS Code](/integrations/connect-vs-code/)
- [ChatGPT](/integrations/connect-chatgpt/)
- [Codex](/integrations/connect-codex/)
- [Grok (grok.com)](/integrations/connect-grok/)
- [Cursor](/integrations/connect-cursor/)
- [Grok Build](/integrations/connect-grok-build/)

Software that acts on its own, under an identity of its own, is not an AI client: it is an agent. See [Registering an agent](/integrations/registering-an-agent/) and [Agents and AI clients](/integrations/agents-and-ai-clients/).

### Which clients can connect

Any MCP client that follows the MCP authorization specification can connect to a Floxar account whose administrator has turned MCP on. That means OAuth 2.1 with PKCE, and a client that identifies itself in one of two ways:

- **A Client ID Metadata Document.** The client's identifier is the HTTPS address of a small JSON document its maker publishes. Most clients work this way and need nothing from you but your account URL.
- **An identifier Floxar publishes.** Some clients publish no document but let you enter a client ID in their configuration. Floxar publishes one identifier per such client; today `cursor` and `grok-build`. There is never a client secret.

Floxar does not offer dynamic client registration, which the MCP specification has deprecated. A client that can only register itself, with no place to enter an identifier and no published document, cannot connect.

Floxar has read the registration of each client in the list above and connected it end to end. At sign-in, those clients appear under Floxar's own label for them. A client that is not on the list connects the same way, as long as it publishes a Client ID Metadata Document and sends your account URL as the resource it is asking for; the difference is what the consent page shows (see "Any other client" below).

### Before you start

- **MCP must be turned on for your account.** It starts off for every account. An account admin turns it on under MCP Connections in the account settings.
- **You need your account URL.** Every Floxar account has its own MCP URL, of the form `https://mcp.floxar.com/a/<account_id>`. You find it on the MCP page of the Floxar application (under Automations, then Agents), which also shows whether MCP is on for your account. Account admins also see it on the MCP Connections page. It is the only URL you need: there are no API keys or tokens to copy.
- **Some clients need a client ID.** If your client asks for one, use the identifier Floxar publishes for it, shown in that client's guide. Leave any client-secret field empty.

### How connecting works

The first time a client connects, it opens a browser window on Floxar's sign-in:

1. **Sign in** with your usual Floxar login.
2. **Confirm the account.** The page shows who you are signed in as, the account your account URL belongs to, and that URL. The connection works in that account only. If the page shows a login that is not the one you meant, choose Deny, sign out of Floxar, and start the connection again from your client.
3. **Read who is asking.** For a verified client, the page shows Floxar's label for it, the domain it identifies itself with (or its vendor, for a published identifier) and where the connection returns to. For any other client, it shows the client's domain as the heading, its full identifier beneath, the name the client declares for itself marked as the client's own claim, where it returns to, and the notice "Floxar has not reviewed this client." A client running on your own computer returns to a local address, and the page says so: an identifier names a client, not the program on your machine that is listening.
4. **Allow the connection.** The page lists what the client will be able to do, limited to what your account allows MCP clients, and says whether the connection can stay connected without signing in again, for up to 7 days of inactivity. Choose Allow, or Deny to stop. You allow or deny the connection as listed; there is no per-capability choice.

### What the capabilities mean

A client asks for capabilities, which OAuth calls scopes. There are three:

| Scope | What the consent page says |
| --- | --- |
| `floxar.read` | Read your flows, steps, references and trails. |
| `floxar.execute` | Run and update trails on your behalf. |
| `floxar.author` | Create and edit flows, steps and references on your behalf, including archiving steps and references, removing connections and changing a flow's status. |

A client may also ask for `offline_access`, which is how it asks to stay connected.

- **A capability is a ceiling, not a grant.** What the connection can do is the capabilities you allowed, intersected with your role in the account. A client never gets more than your role allows.
- **Reading comes with the others.** A connection allowed to run trails or to author can also read, even if the client did not ask for it.
- **The client only sees what it may use.** The tool list a client receives leaves out every tool the connection's capabilities do not cover, so a read-only connection never sees a write tool.
- **The account can narrow what is offered.** An account admin sets which capabilities MCP clients may have in the account; the consent page lists what the client asked for, narrowed by that setting.

### Any other client

1. In your client, add a remote MCP server (HTTP) and paste your account URL as its URL.
2. A client that publishes a Client ID Metadata Document needs nothing else: it identifies itself, and its browser window opens for you to sign in. A client that asks for a client ID needs one Floxar publishes; if Floxar publishes none for your client, it cannot connect that way yet.
3. Sign in to Floxar, then read the consent page: it names the client's domain and the account, and marks a client Floxar has not reviewed. Allow the connection only if you started it yourself and you trust that domain.

If you build an MCP client, see [Publishing a client metadata document](/integrations/publishing-a-client-metadata-document/).

### More than one account

A connection works only in the account whose account URL you added it with. To work in a second account, add Floxar again with that account's URL, under a different name, for example `acme-floxar` and `globex-floxar`. Clients tell servers apart by name, not by URL, so each account needs a distinct server name: some clients refuse a duplicate name, and others replace the earlier entry.

### What an account admin controls

An account admin manages MCP on the account's MCP Connections page in the Floxar application (Account Settings, then MCP Connections):

- **Turning MCP on or off.** It starts off. Turning it off revokes every connection in the account.
- **The capability ceiling.** Which of reading, running trails and authoring MCP clients may be granted, for example read-only. A narrower ceiling applies from the next sign-in; it revokes nothing already connected.
- **Which clients the account accepts.** An account that has said nothing accepts any client that follows the specification, reviewed by Floxar or not; each person's reading of the consent page is the check. An admin can deny a client from a connection's row in the inventory, which also revokes that client's connections in the account, or keep an allow list of the only clients the account accepts (set through Floxar's API). An allow list does not change when Floxar verifies a new client.
- **The connected-applications inventory.** Every connection in the account: the person, the client and whether Floxar has reviewed it, the access it was allowed, its status and, when revoked, the reason, when it was connected and when access was last issued. Any one of them can be revoked from there.

Separately, Floxar keeps a platform-wide block list for clients that abuse the platform. A blocked client is refused in every account and its connections are revoked. Report a client to security@floxar.com.

### Disconnecting and revoking

Disconnecting inside a client does not end the connection on Floxar's side. Removing the connector in Claude or ChatGPT, `claude mcp logout` or `codex mcp logout`, disconnecting in Cursor's or grok.com's settings, signing out in VS Code: each stops that client using the connection, but the connection stays active in Floxar until you or an admin end it there.

- **Your own connections.** In the Floxar application, open your profile's Security page and choose Disconnect applications. This ends every AI client you have connected, in every account.
- **An account admin** can revoke any one connection from the account's MCP Connections inventory, deny the client for the account, or turn MCP off for the account, which revokes every connection in it.

A revoked connection stops working within about 3 minutes. To use the client again, connect it again and allow the connection. Signing out of Floxar, even everywhere, does not disconnect AI clients.

### Good to know

- **Staying signed in.** A connection renews its access on its own, whether or not the client asked to stay connected, as long as the client's registration allows it. After 7 days without use, or 30 days in total, the client asks you to sign in again.
- **Everything is attributed to you.** Actions taken through a connection are recorded under your name, marked as made through MCP, together with the client that made them.
- **Adding access later means reconnecting.** A connection keeps the capabilities it was allowed. If it was made read-only and you later want the client to run trails or author, connect again and allow the connection; the new consent lists the capabilities the connection gets. Each client's guide says how.
- **Your role still applies.** A tool that answers `PERMISSION_DENIED` needs a role you do not have; reconnecting does not change your role.
- **One connection per person, per client, per account.** Connecting the same client to the same account again replaces your earlier connection; it never touches a colleague's.
- **Starting a trail can pause the one you had open.** You have one active trail at a time, so a trail your client starts for you pauses the trail you were working on in the application. Resume it from the application.

### Troubleshooting

- **The client says it needs to authenticate (HTTP 401) after it was working.** Your sign-in expired or the connection was revoked. Authenticate again from the client. Some clients report a revoked connection in their own words; each client's guide lists what it shows and how to reconnect.
- **The client sees fewer tools than you expected.** The connection has only the capabilities it was allowed, and your role limits it further. Reconnect to allow more, or ask an account admin about your role or the account's capability ceiling.
- **A tool answers `PERMISSION_DENIED`.** Your role in the account does not allow that action. Reconnecting does not help; ask an account admin.
- **Disconnecting one client ended another.** Some clients share one connection with a sibling client from the same vendor (Codex with ChatGPT, Grok Build with grok.com). Revoking that connection disconnects both.
- **The sign-in itself was refused.** See the next section.

### If sign-in stops

When a connection cannot be made, Floxar's sign-in page says why. Find the message you were shown:

- **"MCP connections are not enabled for this account"**: MCP is off for the account. Ask an account admin to turn it on under MCP Connections in the account settings.
- **"You are not a member of this account"**: the account URL belongs to an account you are not in. Use your own account's URL, or ask that account's admin to add you.
- **"This account does not accept this client"** (the page may name the account): an administrator of the account decides which clients it accepts, and this one is not among them. Ask an account admin, or connect a client the account accepts.
- **"This account already has connections from 25 clients Floxar has not reviewed"**: the account has reached its limit of unreviewed clients. An account admin can revoke one of them to make room.
- **"This account allows none of the capabilities the client asked for"**: the client asked only for capabilities the account does not allow MCP clients. Ask an account admin which capabilities MCP clients may have.
- **"This account requires a stronger sign-in"**: sign in the way the account requires, for example with an authenticator app, a passkey or your organization's own sign-in, then connect again.
- **"The account is no longer active"**: connect to the URL of an account you can use.
- **"This client has been blocked"**: Floxar has blocked the client for every account.
- **An invalid-client message**: Floxar could not accept the client. A client ID may not be typed exactly as its guide shows, or the client's metadata document could not be read or breaks one of the rules in [Publishing a client metadata document](/integrations/publishing-a-client-metadata-document/).
- **An invalid-scope message**: the client asked for no capability Floxar offers. Check any scopes set in the client's configuration against its guide.
- **An invalid-target message**: the client did not send your account URL as the resource it is asking for, or the URL is not an active account's. Check that the URL you added is exactly your account URL.
- **"Temporarily unavailable"**: the client's document could not be fetched right now, or a client Floxar has not reviewed is not being admitted at the moment. Try again in a few minutes.

The messages about the account and your membership always appear on Floxar's page. Some of the other errors are passed back to a client Floxar has verified, which may show them in its own words; for any other client they stay on Floxar's page and are never sent back to it. For anything else, contact help@floxar.com.

*Last reviewed: 2026-09-30*

---

## Integrations

Floxar has an MCP server, so you can work in your account from your own AI client, or let software work in it under an identity of its own. Connect a client when you want to work in Floxar yourself: you sign in with your usual Floxar login, and each verified client has a short guide with the exact steps. Register an agent when software should act on its own, with its own role and its own place in the audit trail. Agents that act on your own systems can keep the credentials they need in the Secrets Vault, which Floxar can never read.

### [Connecting an AI client to Floxar](/integrations/connecting-an-ai-client/)

Floxar has a Model Context Protocol (MCP) server, so you can work in Floxar from your own AI client: find and read your flows, steps, references and trails, run trails, and create or edit flows. You sign in with your usual Floxar login, and the client can only do what you approve and what your role in the account allows.

### [Registering an agent](/integrations/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.

### [The Secrets Vault](/integrations/the-secrets-vault/)

When an agent runs a flow that acts on your own systems (a CRM it updates, a ticketing tool it closes, an internal API it calls), it needs credentials for those systems. The Secrets Vault is an optional place to keep them. It is built so that Floxar can never read what you store: credentials are encrypted in your browser before they reach Floxar, and only the agents you run can open them, at the moment a step needs them.

### [Agents and AI clients: which one you need](/integrations/agents-and-ai-clients/)

There are two ways to reach Floxar's MCP tools: a person connects an AI client they use, or an account admin registers an agent that acts on its own. Both reach the same account URL, `https://mcp.floxar.com/a/<account_id>`, and the same tools, and both are limited by a role. The rest differs.

### [Connect Claude (claude.ai and Claude Desktop) to Floxar](/integrations/connect-claude/)

claude.ai and Claude Desktop share the same connectors, so you add Floxar once as a custom connector and use it in both. Claude identifies itself to Floxar with its own Client ID Metadata Document: you enter no client ID or secret. Reading, running trails and authoring through Claude are confirmed.

### [Connect Claude Code to Floxar](/integrations/connect-claude-code/)

You add Floxar to Claude Code with one command in your terminal. Claude Code identifies itself to Floxar with its own Client ID Metadata Document, so you enter no client ID or secret.

### [Connect VS Code to Floxar](/integrations/connect-vs-code/)

You use Floxar in VS Code from GitHub Copilot Chat in agent mode. VS Code identifies itself to Floxar with its own Client ID Metadata Document, so you enter no client ID or secret. The connection is confirmed with VS Code 1.139, the desktop editor.

### [Connect ChatGPT to Floxar](/integrations/connect-chatgpt/)

ChatGPT connects to Floxar in developer mode, which is available on ChatGPT Pro, Plus, Business, Enterprise and Education accounts on the web; a workspace's policy can restrict it. ChatGPT identifies itself to Floxar with its own Client ID Metadata Document, so you enter no client ID or secret. Reading and running trails through ChatGPT are confirmed.

### [Connect Codex to Floxar](/integrations/connect-codex/)

The Codex command line, the Codex IDE extension and the ChatGPT desktop app share one configuration, so you add Floxar once. Codex identifies itself to Floxar with its own Client ID Metadata Document, so you enter no client ID or secret.

### [Connect Grok (grok.com) to Floxar](/integrations/connect-grok/)

You add Floxar to Grok on grok.com as a custom connector. Grok identifies itself with its own Client ID Metadata Document, so it needs no client ID or secret from you. Reading and running trails through Grok are confirmed. Grok Build, the command-line client, is a separate client with a guide of its own: Connect Grok Build.

### [Connect Cursor to Floxar](/integrations/connect-cursor/)

Cursor's desktop application and command line share one `mcp.json`. Cursor publishes no metadata document, so it identifies itself with the identifier Floxar publishes for it, `cursor`. There is no client secret. The connection is confirmed with Cursor 3.22.12 (desktop).

### [Connect Grok Build to Floxar](/integrations/connect-grok-build/)

Grok Build, the command-line client, identifies itself with the identifier Floxar publishes for it, `grok-build`. There is no client secret. The connection is confirmed with Grok Build 1.0.44. Grok on grok.com is a separate client with a guide of its own: Connect Grok (grok.com).

### [Publishing a client metadata document](/integrations/publishing-a-client-metadata-document/)

If you build an MCP client, no registration with Floxar is needed. Publish a Client ID Metadata Document and use its HTTPS URL as your `client_id`. Floxar fetches the document when your client first asks to connect, and the URL's domain is what people see when they are asked to allow the connection. The rules are those of the IETF client-ID-metadata-document draft, with a few narrowings described here.

---

## Publishing a client metadata document

If you build an MCP client, no registration with Floxar is needed. Publish a Client ID Metadata Document and use its HTTPS URL as your `client_id`. Floxar fetches the document when your client first asks to connect, and the URL's domain is what people see when they are asked to allow the connection. The rules are those of the IETF client-ID-metadata-document draft, with a few narrowings described here.

For what a person sees and does when connecting, see [Connecting an AI client](/integrations/connecting-an-ai-client/).

### How your client finds Floxar

Each Floxar account has its own MCP URL, the account URL, of the form `https://mcp.floxar.com/a/<account_id>`. The person gives your client that URL. An unauthenticated request to it answers HTTP 401 with a `WWW-Authenticate` header pointing at the account's protected-resource metadata. That metadata names the authorization server, `https://tokens.floxar.com`, and the scopes Floxar offers. The authorization server's metadata says it supports client ID metadata documents and advertises no registration endpoint: Floxar does not offer dynamic client registration.

### The URL

- HTTPS, with a path other than `/`.
- No query, port, fragment or user info.
- A DNS host name, not an IP address or `localhost`, written in lower-case ASCII exactly as it will be presented.
- At most 512 characters.

### The document

- JSON, served with a JSON content type, at most 5 KB, from the URL itself. A redirect is a failed fetch.
- `client_id` equal to the URL.
- `client_name` of at most 100 characters. People see it marked as your client's own claim.
- One to ten `redirect_uris`, each either HTTPS on the same origin as the document, or an `http` loopback address (`localhost`, `127.0.0.1` or `[::1]`, any port) for a native client.
- A public client: `token_endpoint_auth_method` set to `none`, or `none` among the methods you list. Your client authenticates with PKCE alone.
- `grant_types` including `authorization_code`, and `refresh_token` if you want to stay connected.
- `response_types` including `code`.

Nothing else in the document is read or fetched; no logo is shown. A document that declares a client secret is refused.

```json
{
  "client_id": "https://client.example.com/oauth/client-metadata.json",
  "client_name": "Example Client",
  "redirect_uris": ["https://client.example.com/oauth/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}
```

### Redirect URIs

A redirect URI is matched exactly, as a string, with one exception: a native client's `http` loopback redirect matches whatever its port. `localhost`, `127.0.0.1` and `[::1]` never stand for one another, so register the one your client actually uses. Custom schemes are refused.

### What gets a document refused

- A redirect URI on another host than the document's, or on a custom scheme.
- A document over 5 KB.
- A redirect instead of the document.
- A shared-secret authentication method.
- A `web` client with a loopback redirect.

A refused client sees Floxar's error page, with the reason, and is never redirected.

### The request

- **Ask for exactly one `resource`:** the account URL the person entered. Floxar has no account picker; each account is its own URL.
- **Use PKCE** with the S256 method.
- **Take your scopes from the protected-resource metadata:** `floxar.read`, `floxar.execute` and `floxar.author`. Ask for at least one; a `scope` that names none of them is refused. A request with no `scope` at all is taken as asking for the three, without staying connected. Add `offline_access` to ask to stay connected.

### Staying connected

If your document's `grant_types` includes `refresh_token`, Floxar issues a refresh token whether or not you asked for `offline_access`. Refresh tokens rotate on every use. After 7 days without use, or 30 days in total, the person is asked to sign in again. A client whose document does not name the grant gets no refresh token and must send the person through sign-in again when its access expires.

### Caching

Your document's `Cache-Control: max-age` is honoured between 5 minutes and 24 hours, and taken as 1 hour when absent. A change to the document takes effect at the next fetch; connections already made stand. A connection is tied to your domain, not to the name the document declares, so it survives a change of name; the next consent shows the new name.

### Errors and the consent page

Until Floxar has reviewed your client, the consent page is headed by your document's domain, shows the full URL beneath it, marks the name you declare as your own claim, and tells the person that Floxar has not reviewed the client. Authorization errors for your client are shown on Floxar's error page and never redirected to you; the exception is `access_denied`, which returns to your client after the person chooses Deny, or after Floxar has refused the account and the person has read why.

### Becoming a verified client

Floxar keeps a list of clients it has verified: it reads the client's registration and connects it end to end. A verified client appears at consent under Floxar's own label, with no not-reviewed notice, and its errors are redirected to it as OAuth has it. Verification changes how your client is shown and served, not whether it can connect: any client that follows these rules can connect to an account that accepts it. An account admin can still deny any client, verified or not.

*Last reviewed: 2026-09-30*

---

## 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](/integrations/connecting-an-ai-client/). Register an agent when software acts on its own, under an identity of its own. [Agents and AI clients](/integrations/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. |



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.

```bash
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:

```json
{ "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:

```text
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:

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

The official TypeScript MCP client:

```typescript
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:

```text
{ "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*

---

## The Secrets Vault

When an agent runs a flow that acts on your own systems (a CRM it updates, a ticketing tool it closes, an internal API it calls), it needs credentials for those systems. The Secrets Vault is an optional place to keep them. It is built so that Floxar can never read what you store: credentials are encrypted in your browser before they reach Floxar, and only the agents you run can open them, at the moment a step needs them.

You do not need the Vault to use agents. If you already run a secrets manager, your agents can keep using it. The Vault is for teams that want a safe place for these credentials next to the flows that use them.

### How your secrets stay unreadable to Floxar

- **Encrypted before they leave your browser.** When an admin saves a credential, the browser encrypts it first. Floxar only ever receives the encrypted form.
- **A key split in two.** Each secret is locked with a key that is split between you and Floxar. Floxar keeps one half; the other half is sealed to a recipient key whose private part stays with you. Neither half opens anything alone, so Floxar's servers never hold a readable secret, and a breach of Floxar's storage would not expose your values.
- **Opened on your side.** An agent you run asks the Vault for a secret it has been granted, receives the locked material and Floxar's half, and opens it in memory with the private key file you gave it.
- **Referenced by name.** Flows and trails refer to a credential by its name (its handle), never by its value. A trail records that a step used a credential and which version, not the credential itself.
- **Kept apart.** The Vault runs on isolated infrastructure with its own storage, separate from where your flows and trails live.

### Turning it on

The Vault is switched on per account. If it is not yet available on yours, ask at help@floxar.com. Once it is, an account admin opens it from the Floxar application (Resources, then Secrets Vault) at vault.floxar.com and enables it for the account, which includes accepting the Vault's terms. Only account admins manage the Vault.

### Setting it up

1. **Create a recipient key.** On the Keys tab, generate a key in your browser. You download the private key file and confirm you kept it; Floxar receives only the public part. Keep the file safe and give it only to the agents that should open your secrets. You can use one shared key for all your agents or separate keys to keep them isolated.
2. **Store a secret.** On the Secrets tab, add a secret with a handle (the name flows will use), its type and its value. The value is sealed in your browser before it is stored.
3. **Grant an agent access.** For each secret, choose which registered agents may resolve it and with which recipient key, optionally until an expiry date. Access is denied by default: an agent without a grant cannot resolve the secret, whatever its role. See [Registering an agent](/integrations/registering-an-agent/) for creating the agent itself.
4. **Reference it in a flow.** Authors add a credential reference to the step that needs it, naming the handle and what it is for. Admins can let authors and authoring agents see the list of available credential names, without their values, on the Catalog access tab.

### At run time

When a step needs a credential, the agent authenticates to Floxar with its own agent credentials, resolves the handle through the Vault's agent API, and opens the value in memory. The Vault checks that the agent holds an active grant for that secret before it releases anything, and applies rate limits per agent and per account. Agents may cache a resolved value for a short, bounded time.

### Rotating, revoking and auditing

- **Rotate** a secret to replace its value with a new version; agents pick up the new version on their next resolve.
- **Remove an agent's access** or **revoke** a secret to stop future resolves. This cannot recall a value an agent has already opened or cached. If a credential may have leaked, rotate it in the system it belongs to; that is the only way to cut off a copy that is already out.
- **Access log.** Each secret has a log of who or what managed or resolved it, when, and with what outcome. Floxar can show you this log precisely because it holds no readable secret behind it.

### Your responsibilities

The Vault is a working copy for running flows, not your system of record. Keep your own copy of every credential you store, and keep your private key files backed up: Floxar cannot recover a lost private key or a secret sealed only to it. If you lose a key, create a new one and store the affected secrets again.

*Last reviewed: 2026-09-30*