Core concepts
Organizations, projects, locations, circuits, chargers and drivers: the handful of things Flowion models and how every API call is scoped by them.
On this page
Flowion models a small set of things, and every API call is scoped by them. Learn these and the shape of the whole API follows.
Organization your account: members and billing
└─ Project one charging operation, live and sandbox
├─ Location a place: a depot, a car park, a building
│ └─ Circuit the wiring there, as a tree with ratings
│ └─ Energy monitor measures a circuit's real load
├─ Charger one charging station
│ └─ Outlet charges one car at a time
│ └─ Connector a socket or a cable
├─ Driver someone allowed to charge, with their cards
└─ Session one car's visit, start to finish
An outlet draws its power through a circuit, which is how Flowion knows which chargers share which wires.
Organization
Your account, and where membership and billing live. Live usage in every project of the organization is billed to its billing account, which can pay for several organizations and pools one free allowance across them.
An organization has a name, for people, and a slug, which you choose: lowercase letters and digits in hyphen-separated segments, at most 63 characters, unique across Flowion. The slug can appear in a charger's connection address, so pick one you will keep.
Creating an organization also creates its first project, prod, and makes you the organization's Owner.
Project
A project is one charging operation: a brand, a client you run chargers for, or a country. Most organizations need one. Chargers, locations, sessions, drivers and cards each belong to exactly one project, and nothing crosses from one project to another. Access is given per project, which makes it the boundary to reach for when you think "tenant".
One project is the organization's default. A charger whose connection address names no project connects to it.
Every project has two modes, live and sandbox. Each credential works in one of them at a time. Live is your real fleet. Sandbox is where you build and test: it runs virtual chargers, and nothing in it reaches a real charger or a real invoice.
A project can carry a time zone, the IANA name (Europe/Stockholm) your team reads its times in. Projects covers when to add one.
Location
A physical place: a depot, a car park, an office building. A location carries its own price zone, the electricity market its day-ahead prices come from, and can carry its own time zone, so one project can span several countries.
Circuit
The wiring at a location, as a tree. A circuit with no parent is a Main circuit, the connection to the grid; every other circuit hangs off the one that feeds it. Each circuit has a phase count (1 or 3), a rated current in amperes and, when it is single-phase, the line it is wired to (L1, L2 or L3).
Every location starts with a Main circuit. Flowion refuses a circuit tree that promises more current than its wiring can carry, so a child's rating always fits within what its parent has left.
Circuits are what let Flowion share a site's power between the cars charging there. Each outlet is placed on the circuit that feeds it, so two outlets of one charger can sit on different circuits. See Model a site's circuits.
Energy monitor
A meter that measures the current actually flowing through a circuit, including everything that is not charging: lights, heat pumps, machines. Assign one to a circuit and Flowion gives charging the capacity the rest of the building leaves free. See Add an energy monitor.
Charger
One physical charging station. It has a charge point id, the name it introduces itself with when it connects. That id is unique within a project, not across Flowion, so everything else in the API addresses a charger by its UUID.
Creating a charger returns an authorization key, its password. The key is shown once and stored only as a hash. If you lose it, rotate it.
| Field | Tells you |
|---|---|
status | online while the charger holds a connection, otherwise offline |
lastSeen | When it last communicated; kept after it disconnects |
serviceState | Whether it may start charging for drivers now, and if not, why |
disabledAt | When it was deprovisioned; null while it may operate |
status can trail reality by a moment after a connection drops; lastSeen is the durable record. Deprovisioning a charger is permanent: its credential stops working and its history stays readable.
Outlet and connector
An outlet charges one car at a time; the API calls it an EVSE. A connector is one socket or tethered cable on an outlet. A post with two cables sharing one power module is one outlet with two connectors.
A charger reports its own outlets and connectors when it connects. You can also declare its outlets when you create it, each on its circuit, so load management covers it from its very first session.
Session
One car's visit to one outlet, from start to finish. Flowion records it as it happens: when it started, each meter reading, and when and why it ended. The energy delivered is worked out from the meter readings. See Track sessions, energy and cost.
Driver and card
A driver is someone allowed to charge; the API calls it a principal. Permission belongs to the driver: you give them the Charging policy at a project, a location or a single charger, and they may charge there. A card (an RFID tag, a key fob, an app token) only says who is charging, so a driver can hold several cards, and a lost card is blocked without touching the driver's permissions. See Let drivers charge with RFID cards.
Members and policies
People belong to an organization as members. What a member may do is a set of named permissions, given by policies: Owner, Admin and User. A policy is held across the organization or at one project, so an Admin at the organization reaches every project, and a User at one project reaches only that project. There is exactly one Owner. See Permissions and policies.
How this shapes the API
You create things under their parent. A project under an organization, a charger or a location under a project, a circuit under a location.
You read and change things by their own id. Once something exists you address it directly, /v1/charging-stations/{id} or /v1/circuits/{id}, without repeating its parents. Flowion checks your access to the whole chain for you.
The API reference lists every endpoint.