Concepts/Create an App

🧩 Create an App

An app is what a client signs into: one identifier, its own users, a default role for the people who join, and the robots you assign to it.

What an app is

The identifier is the handle every client sends at login — lowercase, underscore-separated, and globally unique rather than per organisation. A login request carries no organisation, so there is nothing to disambiguate a collision with; a taken identifier is refused 409 identifier_taken.

Six identifiers are reserved: mcp, oauth, welcome, healthz, realtime and bridge. Each is a fixed segment of the MCP host, so an app holding one would be listed in the console with an MCP endpoint nobody can reach. Creation refuses them with 400 validation_error naming identifier.

There is no rename. PATCH /api/apps/:id changes the display name and the robots, and the identifier is not among them. Getting a different one means a different app.

An app owns its own users, and nothing about them is shared between apps. The roles they hold belong to the organisation and are the same in every app.

An app user belongs to exactly one app, so one address may be two unrelated accounts in two apps of the same organisation. Your own console login is a Fleetless user and signs into no app at all — see Manage users and roles.

Assign robots

An app reaches only the robots listed on it, each referenced individually. Pass robot_ids when you create the app, or attach a robot later on its page in the console.

A robot that is not assigned does not exist for that app. Every route addressing it answers 404 not_found — the same answer a robot in another organisation gets. An app cannot tell the two apart.

Assignment is not a filter. Once a robot is attached, every exposure it declares is reachable in principle, and the user’s role and the app’s locks narrow it. See Exposing a Robot and Roles and Rights.

Auth configuration

One row per app, read whole at /api/apps/:id/auth-config and written in five slices — .../auth-config/registration, .../auth-config/sign-in, .../auth-config/urls, .../auth-config/mcp and .../auth-config/look — plus the logo as a raw body at .../auth-config/logo. Each PUT replaces only its own slice, every field of that slice required, and refuses a field it does not know rather than dropping it quietly; the merge against the stored row happens server-side, so writing one slice never disturbs the others. Each answers the whole document back, same as the GET.

Slice Field What it does
registration self_registration Whether a stranger may create an account. Off refuses register with 403 registration_closed.
registration allowed_domains The address domains self-registration accepts. Empty means no restriction, not nobody — the switch above is what closes the door.
registration allowed_origins The origins CORS is answered for on every route an app-user bearer reaches, refusals included, and the only origins an OIDC redirect_uri may name. Bare origins: scheme, host, port, no path. Up to 20.
sign-in sign_in_methods Which credential-based methods your users may sign in with: password, email_code, or both. At least one. An email code is six digits, valid ten minutes, and spent after five wrong attempts.
sign-in two_factor off, optional or required. See two-factor, below.
urls app_url Your app’s own home page. The hosted “done” pages offer Open <app> when it is set, and “You can close this tab” when it is null.
urls verify_url The page in your app that confirms a new address, carrying {token}. Unset, a Fleetless-hosted page does it instead — see hosted pages, below.
urls reset_url The page that takes a new password, carrying {token}. Same fallback.
urls invite_url The page that accepts an invitation, carrying {token}. Same fallback.
urls mcp_login_url The page an MCP authorization sends the browser to, carrying {interaction}. Same fallback. Moved here from the mcp slice; a PUT .../mcp naming it is refused.
mcp mcp_enabled Whether the app serves MCP at /mcp/<identifier>. Off refuses the whole OAuth surface, not only the tool calls.
look hosted_accent The accent colour of the hosted pages, a lowercase #rrggbb. null keeps the neutral default.
— hosted_logo_url Read-only; set with PUT/cleared with DELETE /api/apps/:id/auth-config/logo (raw body, PNG or SVG, at most 512 KB; a PNG at most 4096 × 4096 pixels; five uploads at once per organisation, then one a minute). null until you upload one.
— hosted_pages Read-only: the Fleetless-hosted URL for each of invite_url, verify_url, reset_url and mcp_login_url, whether or not you have set your own.
— oidc_callback_url Read-only, minted by the cloud. The one callback to register at every provider, and refused in every slice’s write for the same reason.

The CORS decision is answered on every route an app-user session reaches, refusals included, not only under /api/client/. An app reads its robots through routes that carry no client prefix.

An origin missing from allowed_origins does not produce a 403. It produces a failure with no status and no body, because the browser discards the answer before your code sees it. This is the first thing to check when every call fails at once.

Every one of the four link URLs is optional. Leave invite_url, verify_url, reset_url or mcp_login_url unset and nothing is refused for its absence any more: Fleetless serves its own page at the matching hosted_pages URL instead, so self-registration, mailed invitations, password resets and MCP sign-in all work before your app has a page of its own — handy in local development, and for an app with no web UI at all. A URL you do set still wins, exactly as before.

A set URL is https, or http on loopback while you build locally, and carries its placeholder exactly once: substitution replaces the first occurrence, so naming it twice mails a half-substituted link and naming it not at all mails every recipient the same one. The check cannot see whether the URL resolves, or whether your page knows what to do with the token.

Hosted pages

A Fleetless-hosted page is a plain server-rendered form on the auth portal, under /app/<identifier>/…; it calls the same /api/client/* routes your own page would, so there is one policy, not a second copy. It carries your app’s name, the logo and accent colour from the look slice, and Secured by Fleetless at the bottom.

The logo and the accent colour need the Plus plan or above; on Basic the page carries the name only — never your users’ Fleetless-branded console. It is not a login for your app’s own web UI: it hands nobody a session at your origin, only at Fleetless’s own routes.

Two-factor for your app

two_factor asks for a TOTP authenticator on top of whatever sign_in_methods lets a user sign in with, with ten single-use recovery codes as the fallback — there are no passkeys on this side (those are a Fleetless-user thing, see Sign-in and Two-Factor).

  • off — never asked.
  • optional — a user turns it on from your app’s own account settings (the hosted pages have none); once on, every sign-in asks for it.
  • required — a user with no authenticator sets one up right after their next sign-in, before any session exists; nobody already signed in is signed out when you switch it on.

Sign-ins through an OIDC provider skip this, whatever the policy says: the provider owns that sign-in. Everywhere else, no path hands out a session without the second factor once a user has a confirmed authenticator — even under optional, for that one user.

Identity providers. An app may carry any number of OpenID Connect providers under /api/apps/:id/oidc-providers, and discovery runs when you write one. Identity providers need the Plus plan or above; below it a write answers 403 plan_required. A client_secret is required on create and is echoed back by no route, not even the write’s own answer.

Mail templates. Fleetless sends four mails on your app’s behalf: invite, verify, reset and login_code, the sign-in code. Each default has a text part and an HTML part that carries your app’s name, logo and accent, as the hosted pages do: logo and accent on the Plus plan or above, otherwise two initials on #161616. Under the mail stand your app’s name with Operator information and Privacy policy, when both links are set, and Secured by Fleetless.

Any of the four can be replaced with your own Liquid template. A custom template is sent exactly as written: no layout goes around it, and it has an HTML part only if you wrote one. Liquid runs in strict mode, so an unknown variable fails at save time rather than rendering empty in somebody’s inbox. The permitted set has sixteen names:

Variable What it holds
app.name Your app’s name.
org.name The name of the organisation the app belongs to.
user.email The recipient’s address.
user.display_name The recipient’s display name, or null. In verify and reset whoever registered typed it, so the defaults greet by address.
role.name The display name of the organisation role an invitee will hold, not its key.
link The link the mail exists for: accept, confirm, reset. Empty in login_code.
expires_in_hours How long link works, in hours: 168, 24 or 1. 0 in login_code.
code The six-digit sign-in code. Only in login_code.
expires_in_minutes How long code works, in minutes: 10. Only in login_code.
app.operator_info_url Your operator information page, or null unless both legal links are set.
app.privacy_policy_url Your privacy policy, or null unless both legal links are set.
app.accent The accent as #rrggbb: yours where the plan includes the logo and accent, otherwise #161616.
app.on_accent #000000 or #ffffff, whichever reads better on app.accent.
app.initials One or two letters of the app’s name, as on the hosted pages.
app.logo_src What goes into an <img src>: cid:app-logo@fleetless.dev in a sent mail, a data: address in a preview, null when the app has no logo to show — none uploaded, or a plan without it.
app.logo_shape square, wide or null, beside app.logo_src. The picture is 64 × 64 pixels when square, 336 × 64 when wide; the defaults show it at half that.

A mail does not carry the logo you uploaded. At upload Fleetless also draws it as a small PNG on white, and a sent mail attaches it only when its HTML refers to app.logo_src. A PNG of more than 4096 × 4096 pixels is refused with a message of its own, and an SVG that cannot be drawn with This logo cannot be drawn. Upload a PNG, or an SVG without external references.

The default role

default_role is the key of the organisation role an app user gets when they are created, invited or self-registered without an explicit one. A new app has none, and null is the normal state: every app exists before anybody has said who joins as what.

Choose it on the app’s Access page, next to the locks, or write it with PUT /api/apps/:id/access or over MCP with console_apps_write set_access. That write replaces the whole access, so read it first. A key that names no role is accepted and warns, and the users who get it reach nothing.

Until it is set, self-registration cannot complete: POST /api/client/register answers 409 target_state_conflict naming default_role. Creating or inviting an app user without a role is refused the same way, naming the same field, rather than producing a user with no role.

register asks two questions in order, and verify_url is the first. A fresh app whose verification URL is unset is refused before the role is even looked at, with the same 409 target_state_conflict naming verify_url — so read which field the refusal names rather than assuming which setting is missing.

An invitation resolves its role when it is issued and stores it. Changing the default therefore never re-aims an invitation already in somebody’s mailbox.

Server keys

A server key is a per-app secret carrying the app’s full permission set, for your own backend, automation or continuous integration. No role narrows it. The app’s robot list and the app’s locks still do: a key reaches exactly the robots assigned to its app, less what the app locks.

The secret is returned once, by the call that mints or rotates it, and only its hash is kept. rotate replaces the secret and keeps the key; deleting the key removes the row itself. Minting, rotating and deleting are developer actions, in the console, over REST and over MCP: any developer, and any developer’s AI tool, can do all three.

The old secret stops working immediately, and what is already holding it is cut rather than left running: an open realtime socket, and any live camera session.

A server key never goes into a client. It holds every right the app has, and a browser bundle is a place where secrets are published, not stored.

Talk to it

Install the SDK with npm i @fleetless/sdk, then sign in as an app user and read a value.

ts
import { createClient } from '@fleetless/sdk'

const client = createClient({
  apiUrl: 'https://api.fleetless.dev',
  appIdentifier: 'warehouse_dash',
})

await client.auth.login('someone@example.com', 'correct-horse-battery')
const battery = await client.datapoints.get('robot-id', 'battery_percentage')
console.log(battery.value, battery.timestamp_ms)

The same two steps over plain REST are POST /api/client/login and GET /api/robots/:id/datapoints/:slug with the returned access token as a bearer. See the SDK reference and the API reference.

Next