Menu

Set up your workspace

Create your organization, get an API key, describe your locations, add your first charger and invite your team, in an order you will not regret.

4 min readEdit this page
On this page

Before your first charger goes live, set up what surrounds it: your organization, an API key for your backend, the places you charge at, and the people who run them. Most of it takes a minute. The few choices that are hard to change later are called out where you make them.

The examples use $API for https://api.flowion.io/v1 and $TOKEN for your credential.

Create your organization

Sign in to the console and create your organization there. Creating one is something a person does, so it needs a signed-in session; everything after it can be done with an API key.

You give it two names:

  • name is for people. Change it whenever you like.

  • slug is a short identifier: lowercase letters and digits in hyphen-separated segments, at most 63 characters, unique across Flowion. A slug someone else has is refused with 409.

Choose the slug with care. It can be part of the address your chargers connect to (wss://ocpp.flowion.io/acme), and a charger configured with that address needs the new one if the slug ever changes.

You become the organization's Owner, and it comes with one project, prod, ready to use. You can also store the company's registration number as organizationNumber, with the country that issued it as organizationNumberCountry (a number without a country is read as Swedish).

Get an API key for your backend

A signed-in session is for people in the console. Your backend uses an API key. Create one in the console, or with the API:

POST/v1/organizations/$ORG/api-keysbash
curl -X POST "$API/organizations/$ORG/api-keys" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Backend", "mode": "live",
       "policyBindings": [{"policyId": "'"$ADMIN_POLICY"'"}]}'

A key holds one policy. Admin at the organization (no projectId) reaches every project; User at a project (name it in projectId) reaches that one project. Get the ids from List permission policies. mode is live or sandbox; build against sandbox first, where virtual chargers stand in for hardware.

API keys and sign-in covers keys in full.

Add a project, if you need one

prod is enough for most organizations. Add a project only for a genuinely separate operation, such as a second brand, a client whose chargers you run, or another country:

POST/v1/organizations/$ORG/projectsbash
curl -X POST "$API/organizations/$ORG/projects" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Nordics", "slug": "nordics"}'

Set the time zone your team reads the project's times in:

PATCH/v1/organizations/$ORG/projects/$PROJECTbash
curl -X PATCH "$API/organizations/$ORG/projects/$PROJECT" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"timeZone": "Europe/Stockholm"}'

Projects explains when a second project pays off and when a location is the better fit.

Describe your locations

A location is a place you charge at. Create one per site:

POST/v1/projects/$PROJECT/locationsbash
curl -X POST "$API/projects/$PROJECT/locations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Depot A",
       "address": {"line1": "Hamngatan 1",
                   "city": "Stockholm", "country": "SE"}}'

Give it a price zone to get day-ahead electricity prices for it, and a time zone if it differs from the project's:

PATCH/v1/locations/$LOCATIONbash
curl -X PATCH "$API/locations/$LOCATION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"priceZone": "10Y1001A1001A46L",
       "timeZone": "Europe/Stockholm"}'

priceZone is the market's EIC code; the example is SE3, the zone Stockholm is in.

Each location starts with one Main circuit, the connection to the grid. Add the circuits beneath it, with their ratings, and Flowion can share the site's power between the cars charging there. See Model a site's circuits.

Add your first charger

POST/v1/projects/$PROJECT/charging-stationsbash
curl -X POST "$API/projects/$PROJECT/charging-stations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chargePointId": "DEPOT-A-01"}'

chargePointId is the name the charger introduces itself with when it connects. It must match what the hardware is configured with, exactly, including case. It is unique within the project. A scheme like a site prefix and a number reads well and survives a unit being swapped.

Three optional fields are worth knowing:

  • currentType: AC (the default) or DC.

  • evses: the charger's outlets, each with the circuit that feeds it, so load management covers the charger from its first session.

  • externalVendor and externalModel: the brand and model, shown until the charger reports its own.

Creating chargers needs the asset.charger.provision permission. There is no limit on how many chargers your organization can have; each one is billed as an outlet. Sandbox mode has no physical chargers; use a virtual charger there.

Now connect it.

Invite your team

Invite people by email, with the policies they should hold:

POST/v1/organizations/$ORG/invitationsbash
curl -X POST "$API/organizations/$ORG/invitations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "ops@acme.example",
       "policyBindings": [
         {"policyId": "'"$USER_POLICY"'", "projectId": "'"$PROJECT"'"}
       ]}'

The response carries a token, once. Send the person this link yourself: https://console.flowion.io/account/invitations/{token}. They accept it signed in with the invited address. The console's Members page does all of this for you.

The Admin policy at the organization reaches every project. The User policy at a project reaches only that project, which is how a client's staff get their project and nothing else. Give more later with POST /organizations/$ORG/members/{memberId}/bindings.

There is one Owner. The Owner can hand ownership to another member with POST /organizations/$ORG/members/{memberId}/transfer-ownership, and holds Admin in the same step. See Permissions and policies.

A good order

  1. Create the organization, with a slug you will keep.

  2. Build in sandbox with a sandbox key and a virtual charger.

  3. Set the project's time zone; add a project only for a separate operation.

  4. Create your locations and their circuits.

  5. Add one charger, connect it, and run a session before adding fifty.

  6. Invite your team, giving user members only the projects they need.

In the API reference