Skip to navigation

Concepts

How organizations, domains, asynchronous calls and roaming fit together.

Organizations

Your organization is the tenant. Every token belongs to one organization, and every call only reads and writes that organization’s data. An id from another organization returns 404.

A gateway API

EV Cloud stores no data of its own. Each call is checked against its schema and forwarded to the gateway that owns the data: the CPO, eMSP, energy, webhook or OCPI gateway. When a gateway fails, EV Cloud answers with that gateway’s status and message.

Domains

DomainSDK namespaceREST prefixUse it to
CPOclient.cpo/cpoRun your own charging infrastructure: charge points, locations, tariffs, sessions, CDRs
eMSPclient.emsp/emspIssue driver tokens and choose which partner locations your drivers see
Energyclient.energy/energy-managementCap the power of chargers and read what they draw
Webhooksclient.webhooks/webhook-gatewayGet events on your HTTPS endpoint instead of polling
OCPIclient.ocpi/ocpiConnect to roaming partners and hubs, and push or pull CPO and eMSP data

Asynchronous operations

Some calls finish after the HTTP response: a power limit waits for the charger’s answer, and a roaming command waits for the partner’s result. Those calls return at once and tell you what to poll. See Long-running operations.

Roaming

As a CPO you publish locations, tariffs, sessions and CDRs to partners. As an eMSP you publish driver tokens and receive partner locations. OCPI connects the two: register a partner, run the credentials handshake, then push or pull data.

Records that are kept

Some records have no delete, on purpose, so that billing and audit history stays complete:

  • Driver tokens and token groups (eMSP) end with revoke. A revoked token can no longer charge, but it stays listed.
  • App users (CPO) can be changed with replace but not deleted.
  • Base networks (eMSP) can’t be deleted; an eMSP identity can be deregistered only once it has no networks.
  • Charge points with sessions (CPO) answer 409 Conflict on delete, because deleting them would erase transaction history.
  • OCPI partners can be registered by any user, but only an admin token can remove one.

Environments

The production API is https://api.ev-cloud.ai. Pass it, or another EV Cloud host, as environment (TypeScript), base_url (Python) or --base-url / EVCLOUD_CLI_BASE_URL (CLI).