Frontend API Manager v1 (API Key) (1.0.0)

Download OpenAPI specification:

Entry OpenAPI document for manager controllers exposed through the /v1 route group.

Authentication is done with the API key header:

Header name: X-API-Key

Source layout note:

Shared management operations, schemas, examples, and responses are authored in docs/openapi/common/management.yaml.
Validation with kin-openapi checks references only and does not emit a bundled artifact.

API Keys

List API keys

Returns all API keys associated with the authenticated user.

Authorizations:

ApiKeyHeaderAuth

Responses

Response samples

200
401
500

Content type

application/json

[{"ID": "123e4567-e89b-12d3-a456-426614174010",
"Role": "ROLE_USER",
"ExpiresAt": "2027-04-14T00:00:00Z"
}
]

Create API key

Creates a new API key for the authenticated user.

Authorizations:

ApiKeyHeaderAuth

Request Body schema: application/json
required

Role	string
ExpiresAt	string Go duration string

Responses

Request samples

Payload

Content type

application/json

{"Role": "ROLE_USER",
"ExpiresAt": "8760h0m0s"
}

Response samples

201
400
401
500

Content type

application/json

{"ID": "123e4567-e89b-12d3-a456-426614174010",
"Key": "jp_live_example_key",
"Role": "ROLE_USER",
"ExpiresAt": "2027-04-14T00:00:00Z"
}

Delete API key

Deletes an API key by its ID.

Authorizations:

ApiKeyHeaderAuth

path Parameters

apiKeyId

required

string <uuid>

API key UUID.

Responses

Response samples

400
401
500

Content type

application/json

{"Error": "Invalid request body"
}

Auth Codes

List ID tags

Returns all ID tags for the authenticated user.

Authorizations:

ApiKeyHeaderAuth

Responses

Response samples

200
400
500

Content type

application/json

[{"ID": "TAG001",
"Name": "Reception Tag",
"Type": "RFID",
"Status": "Accepted"
}
]

Create ID tag

Creates an ID tag for the authenticated user.

Authorizations:

ApiKeyHeaderAuth

Request Body schema: application/json
required

ID	string
Name	string
Type required	string
Status	string
ExpiryDate	string <date-time>

Responses

Request samples

Payload

Content type

application/json

{"ID": "TAG001",
"Name": "Reception Tag",
"Type": "RFID",
"Status": "Accepted"
}

Response samples

201
400
500

Content type

application/json

{"ID": "TAG001",
"Name": "Reception Tag",
"Type": "RFID",
"Status": "Accepted"
}

Get ID tag by ID

Returns a specific ID tag for the authenticated user.

Authorizations:

ApiKeyHeaderAuth

path Parameters

id

required

string

ID tag identifier.

Responses

Response samples

200
400
404

Content type

application/json

{"ID": "TAG001",
"Name": "Reception Tag",
"Type": "RFID",
"Status": "Accepted"
}

Update ID tag

Updates an existing ID tag by ID.

Authorizations:

ApiKeyHeaderAuth

path Parameters

id

required

string

ID tag identifier.

Request Body schema: application/json
required

ID	string
Name	string
Type required	string
Status	string
ExpiryDate	string <date-time>

Responses

Request samples

Payload

Content type

application/json

{"Name": "Updated Tag",
"Type": "RFID",
"Status": "Blocked"
}

Response samples

200
400
500

Content type

application/json

{"ID": "TAG001",
"Name": "Main ID Tag",
"Type": "RFID",
"Status": "Accepted",
"ExpiryDate": "2019-08-24T14:15:22Z"
}

Delete ID tag

Deletes an ID tag by ID.

Authorizations:

ApiKeyHeaderAuth

path Parameters

id

required

string

ID tag identifier.

Responses

Response samples

400
500

Content type

application/json

{"Error": "Invalid request body"
}

Billing Models

List billing models

Returns all billing models available to the authenticated user.

Authorizations:

ApiKeyHeaderAuth

Responses

Response samples

200
401
500

Content type

application/json

[{"ID": "123e4567-e89b-12d3-a456-426614174020",
"Name": "Standard Plan",
"DefaultKWHRate": 0.2
}
]

Create billing model

Creates a billing model for the authenticated user.

Authorizations:

ApiKeyHeaderAuth

Request Body schema: application/json
required

property name*

additional property

any

Responses

Request samples

Payload

Content type

application/json

{"Name": "Standard Plan",
"DefaultKWHRate": 0.2,
"DefaultTimeRate": 0.1
}

Response samples

201
400
401
500

Content type

application/json

{ }

Get billing model

Authorizations:

ApiKeyHeaderAuth

path Parameters

modelId

required

string <uuid>

Billing model UUID.

Responses

Response samples

200
400
401
404

Content type

application/json

{ }

Update billing model

Authorizations:

ApiKeyHeaderAuth

path Parameters

modelId

required

string <uuid>

Billing model UUID.

Request Body schema: application/json
required

property name*

additional property

any

Responses

Request samples

Payload

Content type

application/json

{"ID": "123e4567-e89b-12d3-a456-426614174020",
"Name": "Updated Plan"
}

Response samples

200
400
401
500

Content type

application/json

{ }

Delete billing model

Authorizations:

ApiKeyHeaderAuth

path Parameters

modelId

required

string <uuid>

Billing model UUID.

Responses

Response samples

400
401
409
500

Content type

application/json

{"Error": "Invalid request body"
}

Charge Boxes

List charge boxes

Returns charge boxes owned/visible to the authenticated user with optional filters.

Authorizations:

ApiKeyHeaderAuth

query Parameters

ID	string
UUID	string <uuid>
Name	string
UserID	string <uuid>
ChargePointVendor	string
ChargePointModel	string
ProtocolVersion	string
AddressID	string <uuid>

Responses

Response samples

200
400
401
500

Content type

application/json

[{"ID": "CHARGEBOX001",
"UUID": "123e4567-e89b-12d3-a456-426614174000",
"Name": "Main Charger"
}
]

Create charge box

Creates a charge box with a required billing model owned by the authenticated user.

Authorizations:

ApiKeyHeaderAuth

Request Body schema: application/json
required

ID required	string
Name	string
BillingModelID required	string <uuid> Required billing model assigned to the charge box. Must identify an existing billing model owned by the authenticated user.

Responses

Request samples

Payload

Content type

application/json

{"ID": "CHARGEBOX001",
"Name": "Main Charger",
"BillingModelID": "123e4567-e89b-12d3-a456-426614174003"
}

Response samples

201
400
401
500

Content type

application/json

{"ID": "CHARGEBOX001",
"UUID": "123e4567-e89b-12d3-a456-426614174000",
"Name": "Main Charger",
"UserID": "123e4567-e89b-12d3-a456-426614174099",
"ChargePointVendor": "ACME",
"ChargePointModel": "JPLUG-FAST",
"ProtocolVersion": "OCPP 1.6",
"Description": "Parking lot charger",
"Timezone": "UTC",
"BillingModelID": "123e4567-e89b-12d3-a456-426614174003"
}

Get charge box by ID or name

Authorizations:

ApiKeyHeaderAuth

path Parameters

chargeBoxIdOrName

required

string

Charge box ID or Name.

Responses

Response samples

200
400
401
500

Content type

application/json

{"ID": "CHARGEBOX001",
"UUID": "123e4567-e89b-12d3-a456-426614174000",
"Name": "Main Charger",
"UserID": "123e4567-e89b-12d3-a456-426614174099",
"ChargePointVendor": "ACME",
"ChargePointModel": "JPLUG-FAST",
"ProtocolVersion": "OCPP 1.6",
"Description": "Parking lot charger",
"Timezone": "UTC",
"BillingModelID": "123e4567-e89b-12d3-a456-426614174003"
}

Update charge box

Updates a charge box. The resulting charge box must have a billing model owned by the authenticated user.

Authorizations:

ApiKeyHeaderAuth

path Parameters

chargeBoxIdOrName

required

string

Charge box ID or Name.

Request Body schema: application/json
required

ID required	string
Name	string
Description	string
Timezone	string
BillingModelID	string <uuid> Billing model assigned to the charge box. Updates must leave the charge box with an existing billing model owned by the authenticated user.
AddressID	string <uuid>
	object
MaxPower	number or null <double> Maximum charging power in watts. Set to null to disable the setting.

Responses

Request samples

Payload

Content type

application/json

{"ID": "CHARGEBOX001",
"Name": "Main Charger Updated",
"Description": "Parking lot charger",
"Timezone": "UTC",
"BillingModelID": "123e4567-e89b-12d3-a456-426614174003"
}

Response samples

200
400
401
500

Content type

application/json

{"ID": "string",
"UUID": "f50af7e0-0dd5-4361-ab96-2e04f7bc7e30",
"Name": "string",
"UserID": "08aac8e3-775d-4513-8aaa-658f6ba9bbcd",
"ChargePointVendor": "string",
"ChargePointModel": "string",
"ProtocolVersion": "string",
"MaxPower": 0.1,
"Description": "string",
"Timezone": "string",
"BillingModelID": "d8cf3116-a720-430b-bdfc-68ec490fe2ed",
"AddressID": "bfc25713-e79a-4614-a229-6a83766a0388"
}

Delete charge box

Authorizations:

ApiKeyHeaderAuth

path Parameters

chargeBoxIdOrName

required

string

Charge box ID or Name.

Responses

Response samples

400
401
500

Content type

application/json

{"Error": "Invalid request body"
}

Debug

Get request debug info

Returns plaintext diagnostic output for the authenticated request.

Authorizations:

ApiKeyHeaderAuth

Responses

Response samples

401

Content type

application/json

{"Error": "API key is required"
}

Invoices

List invoices

Supports invoice filtering through query params including metadata[key] style filters.

Authorizations:

ApiKeyHeaderAuth

Responses

Response samples

200
401
500

Content type

application/json

[{"ID": "123e4567-e89b-12d3-a456-426614174060",
"Total": 22,
"CurrencyCode": "CAD"
}
]

Get invoice by ID

Authorizations:

ApiKeyHeaderAuth

path Parameters

invoiceId

required

string <uuid>

Invoice UUID.

Responses

Response samples

200
400
401
404

Content type

application/json

{"ID": "123e4567-e89b-12d3-a456-426614174060",
"UserID": "123e4567-e89b-12d3-a456-426614174099",
"Subtotal": 20,
"Total": 22,
"CurrencyCode": "CAD",
"Metadata": {"charge_box_user_id": "123e4567-e89b-12d3-a456-426614174099"
}
}

Get invoice summary

Returns invoice totals grouped by type.

Authorizations:

ApiKeyHeaderAuth

Responses

Response samples

200
401
500

Content type

application/json

{"KWH": 1200.5,
"TAX": 210
}

Organizations

List organizations available to current user

Authorizations:

ApiKeyHeaderAuth

Responses

Response samples

200
401
500

Content type

application/json

[{"ID": "123e4567-e89b-12d3-a456-426614174030",
"Name": "Acme Charging",
"Slug": "acme-charging",
"IsActive": true
}
]

Create organization

Authorizations:

ApiKeyHeaderAuth

Request Body schema: application/json
required

Name required	string
Slug	string
Domain	string
Settings	string

Responses

Request samples

Payload

Content type

application/json

{"Name": "Acme Charging",
"Slug": "acme-charging",
"Domain": "acme.example.com",
"Settings": "{\"timezone\":\"UTC\"}"
}

Response samples

201
400
401
409
500

Content type

application/json

{"ID": "123e4567-e89b-12d3-a456-426614174030",
"Name": "Acme Charging",
"Slug": "acme-charging",
"Domain": "acme.example.com",
"IsActive": true,
"Settings": "{\"timezone\":\"UTC\"}",
"CreatedAt": "2026-04-14T10:00:00Z",
"UpdatedAt": "2026-04-14T10:00:00Z"
}

Get organization by ID

Authorizations:

ApiKeyHeaderAuth

path Parameters

organizationId

required

string <uuid>

Organization UUID.

Responses

Response samples

200
400
401
403
500

Content type

application/json

{"ID": "123e4567-e89b-12d3-a456-426614174030",
"Name": "Acme Charging",
"Slug": "acme-charging",
"Domain": "acme.example.com",
"IsActive": true,
"Settings": "{\"timezone\":\"UTC\"}",
"CreatedAt": "2026-04-14T10:00:00Z",
"UpdatedAt": "2026-04-14T10:00:00Z"
}

Tax Jurisdictions

List tax jurisdictions

Authorizations:

ApiKeyHeaderAuth

Responses

Response samples

200
500

Content type

application/json

[{"ID": "123e4567-e89b-12d3-a456-426614174070",
"Name": "Ontario"
}
]

Themes

List themes

Returns themes belonging to organizations owned by the authenticated user.

Authorizations:

ApiKeyHeaderAuth

query Parameters

domain	string
is_active	boolean

Responses

Response samples

200
500

Content type

application/json

[{"ID": "123e4567-e89b-12d3-a456-426614174040",
"OrganizationID": "123e4567-e89b-12d3-a456-426614174030",
"Domain": "app.example.com",
"Name": "Example Theme",
"IsActive": true
}
]

Create theme

Creates a theme for an organization owned by the authenticated user and generates its immutable hostname.

Authorizations:

ApiKeyHeaderAuth

Request Body schema: application/json
required

OrganizationID required	string <uuid> Organization that will own the theme. The authenticated user must be an owner.
Name required	string
Description	string
required	object (ThemeConfig)

Responses

Request samples

Payload

Content type

application/json

{"OrganizationID": "123e4567-e89b-12d3-a456-426614174030",
"Name": "Example Theme",
"Description": "Theme for the Example charging network",
"Config": {"themeKey": "default",
"language": "en",
"countryCallingCode": "CA +1",
"email": "support@example.com",
"supportLink": "https://example.com/support",
"termsUrl": "https://example.com/terms",
"logoImage": "https://example.com/logo.png",
"logoAlt": "Example Charging",
"title": "Charge with Example",
"description": "Example charging network",
"favicon": "https://example.com/favicon.ico",
"chargerNamePrefix": "EXAMPLE-",
"og": {"title": "Example Charging",
"description": "Example charging network",
"image": "https://example.com/og.png"
},
"designTokens": {"light": {"background": "#fff",
"panel": "#f0f6ff",
"foreground": "#18181b",
"primary": "#19b5e5"
},
"dark": {"background": "#101827",
"panel": "#020817",
"foreground": "#f4f8fb",
"primary": "#19b5e5"
}
}
}
}

Response samples

201
400
404
500

Content type

application/json

{"ID": "123e4567-e89b-12d3-a456-426614174040",
"OrganizationID": "123e4567-e89b-12d3-a456-426614174030",
"Domain": "spark-cyan-harbor.jplug.app",
"Name": "Example Theme",
"Description": "Theme for the Example charging network",
"IsActive": true,
"Config": {"themeKey": "default",
"language": "en",
"countryCallingCode": "CA +1",
"email": "support@example.com",
"supportLink": "https://example.com/support",
"termsUrl": "https://example.com/terms",
"logoImage": "https://example.com/logo.png",
"logoAlt": "Example Charging",
"title": "Charge with Example",
"description": "Example charging network",
"favicon": "https://example.com/favicon.ico",
"chargerNamePrefix": "EXAMPLE-",
"og": {"title": "Example Charging",
"description": "Example charging network",
"image": "https://example.com/og.png"
},
"designTokens": {"light": {"background": "#fff",
"panel": "#f0f6ff",
"foreground": "#18181b",
"primary": "#19b5e5"
},
"dark": {"background": "#101827",
"panel": "#020817",
"foreground": "#f4f8fb",
"primary": "#19b5e5"
}
}
},
"CreatedAt": "2026-04-14T10:10:00Z",
"UpdatedAt": "2026-04-14T10:10:00Z"
}

Get theme by ID

Returns a theme only when the authenticated user owns its organization.

Authorizations:

ApiKeyHeaderAuth

path Parameters

themeId

required

string <uuid>

Theme UUID.

Responses

Response samples

200
400
404
500

Content type

application/json

{"ID": "123e4567-e89b-12d3-a456-426614174040",
"OrganizationID": "123e4567-e89b-12d3-a456-426614174030",
"Domain": "spark-cyan-harbor.jplug.app",
"Name": "Example Theme",
"Description": "Theme for the Example charging network",
"IsActive": true,
"Config": {"themeKey": "default",
"language": "en",
"countryCallingCode": "CA +1",
"email": "support@example.com",
"supportLink": "https://example.com/support",
"termsUrl": "https://example.com/terms",
"logoImage": "https://example.com/logo.png",
"logoAlt": "Example Charging",
"title": "Charge with Example",
"description": "Example charging network",
"favicon": "https://example.com/favicon.ico",
"chargerNamePrefix": "EXAMPLE-",
"og": {"title": "Example Charging",
"description": "Example charging network",
"image": "https://example.com/og.png"
},
"designTokens": {"light": {"background": "#fff",
"panel": "#f0f6ff",
"foreground": "#18181b",
"primary": "#19b5e5"
},
"dark": {"background": "#101827",
"panel": "#020817",
"foreground": "#f4f8fb",
"primary": "#19b5e5"
}
}
},
"CreatedAt": "2026-04-14T10:10:00Z",
"UpdatedAt": "2026-04-14T10:10:00Z"
}

Update theme

Updates a theme only when the authenticated user owns its organization.

Authorizations:

ApiKeyHeaderAuth

path Parameters

themeId

required

string <uuid>

Theme UUID.

Request Body schema: application/json
required

Name	string
Description	string
IsActive	boolean
	object (ThemeConfig)

Responses

Request samples

Payload

Content type

application/json

{"Name": "Updated Theme",
"IsActive": true,
"Config": {"themeKey": "default",
"language": "en",
"countryCallingCode": "CA +1",
"email": "support@example.com",
"supportLink": "https://example.com/support",
"termsUrl": "https://example.com/terms",
"logoImage": "https://example.com/logo.png",
"logoAlt": "Example Charging",
"title": "Updated Theme",
"description": "Updated charging network",
"favicon": "https://example.com/favicon.ico",
"chargerNamePrefix": "EXAMPLE-",
"og": {"title": "Updated Theme",
"description": "Updated charging network",
"image": "https://example.com/og.png"
},
"designTokens": {"light": {"background": "#fff",
"panel": "#f0f6ff",
"foreground": "#18181b",
"primary": "#e11d48"
},
"dark": {"background": "#101827",
"panel": "#020817",
"foreground": "#f4f8fb",
"primary": "#e11d48"
}
}
}
}

Response samples

200
400
404
500

Content type

application/json

{"ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
"OrganizationID": "2d34b1c1-8109-40c1-88f9-fdcfb32ea178",
"Domain": "string",
"Name": "string",
"Description": "string",
"IsActive": true,
"Config": { },
"CreatedAt": "2019-08-24T14:15:22Z",
"UpdatedAt": "2019-08-24T14:15:22Z"
}

Delete theme

Deletes a theme only when the authenticated user owns its organization.

Authorizations:

ApiKeyHeaderAuth

path Parameters

themeId

required

string <uuid>

Theme UUID.

Responses

Response samples

400
404
500

Content type

application/json

{"Error": "Invalid request body"
}

Theme Assets

Upload a theme asset

Uploads the multipart file field as a PNG or JPEG, up to 2 MiB, to one of four supported slots on a theme owned by the authenticated user. Returns the public asset URL without updating the theme configuration.

Authorizations:

ApiKeyHeaderAuth

path Parameters

themeId required	string <uuid>
slot required	string Enum: "logo" "logo-dark" "favicon" "og-image"

Request Body schema: multipart/form-data
required

file

required

string <binary> <= 2097152 characters

PNG or JPEG file no larger than 2 MiB.

Responses

Response samples

Content type

application/json

{"URL": "http://example.com"
}

Transactions

List transactions

Returns transactions with optional filters.

Authorizations:

ApiKeyHeaderAuth

query Parameters

ChargeBoxID	string
idTag	string <= 20 characters
ConnectorID	integer
TimestampStart	string <date-time>
TimestampStop	string <date-time>

Responses

Response samples

200
400
401
500

Content type

application/json

[{"UUID": "123e4567-e89b-12d3-a456-426614174050",
"ChargeBoxID": "CHARGEBOX001",
"ConnectorID": 1,
"IDTag": "TAG001"
}
]

Start transaction

Authorizations:

ApiKeyHeaderAuth

Request Body schema: application/json
required

ChargeBoxID required	string
ConnectorID	integer
IDTag required	string <= 20 characters

Responses

Request samples

Payload

Content type

application/json

{"ChargeBoxID": "CHARGEBOX001",
"ConnectorID": 1,
"IDTag": "TAG001"
}

Response samples

200
400
401
500

Content type

application/json

{"TransactionID": "123e4567-e89b-12d3-a456-426614174050"
}

Get transaction by UUID

Authorizations:

ApiKeyHeaderAuth

path Parameters

transactionUUID

required

string <uuid>

Transaction UUID.

Responses

Response samples

200
400
401
404
500

Content type

application/json

{"UUID": "123e4567-e89b-12d3-a456-426614174050",
"ChargeBoxID": "CHARGEBOX001",
"ConnectorID": 1,
"IDTag": "TAG001",
"TimestampStart": "2026-04-14T10:20:00Z",
"TimestampStop": null,
"MeterStart": 12345,
"MeterStop": null
}

Stop transaction

Authorizations:

ApiKeyHeaderAuth

path Parameters

transactionUUID

required

string <uuid>

Transaction UUID.

Responses

Response samples

200
400
401
500

Content type

application/json

{"Message": "Transaction stopped"
}

Frontend API Manager v1 (API Key) (1.0.0)

API Keys

List API keys

Authorizations:

Responses

Response samples

Create API key

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Delete API key

Authorizations:

path Parameters

Responses

Response samples

Auth Codes

List ID tags

Authorizations:

Responses

Response samples

Create ID tag

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Get ID tag by ID

Authorizations:

path Parameters

Responses

Response samples

Update ID tag

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Delete ID tag

Authorizations:

path Parameters

Responses

Response samples

Billing Models

List billing models

Authorizations:

Responses

Response samples

Create billing model

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Get billing model

Authorizations:

path Parameters

Responses

Response samples

Update billing model

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Delete billing model

Authorizations:

path Parameters

Responses

Response samples

Charge Boxes

List charge boxes

Authorizations:

query Parameters

Responses

Response samples

Create charge box

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required