OCPP Proxy Introduction

About OCPP Proxy

OCPP Proxy is Voltra's intelligent middleware solution that enables seamless communication between EV chargers and third-party charging management systems. This documentation provides comprehensive information on configuring and managing OCPP Proxy using our REST API, including detailed explanations and practical curl examples for all endpoints.

With OCPP Proxy, you can easily connect your chargers to any OCPP-compliant platform while maintaining full control over your charging infrastructure.

Authentication Methods

All endpoints support two authentication methods:

API Key Authentication - For programmatic access and automation
Session Authentication - For web application access via Ory, more details coming soon

Combined Endpoint: Enroll Charger & Configure Proxy

This is the most efficient endpoint for setting up a new proxied charger. It performs two actions in a single atomic transaction:

Creates a new ChargeBox record
Creates the associated ProxyConfiguration for it

Endpoint

POST /api/v1/organizations/{organization_uuid}/chargers/enroll-with-proxy

Field Explanations

Charger Fields (`ChargeBox`)

charge_box_id (string, required): Your unique identifier for the charger
charger_name (string, optional): A human-readable name for the charger. Defaults to charge_box_id
vendor_name (string, optional): The manufacturer of the charger (e.g., "ABB", "ChargePoint")
model_name (string, optional): The model of the charger (e.g., "Terra AC")
serial_number (string, optional): The charger's serial number

Note: Vendor, model, and serial number can be populated later by the charger's first *BootNotification* if omitted.

Proxy Fields (`ProxyConfiguration`)

target_platform_identifier (string, required): A name for the third-party platform (e.g., "SteVe", "ChargeGrid")
target_websocket_url (string, required): The full WebSocket URL of the third-party platform. Supports templating (see below)
target_authentication_method (string, required): Must be one of: "None", "Basic", "ClientCertificate"
target_auth_basic_password (string, conditional): Required only if target_authentication_method is "Basic"
target_auth_client_cert_id (string, conditional): Coming Soon. Required only if target_authentication_method is "ClientCertificate"
target_charge_box_id (string, optional): Use this if the charger needs a different ID on the target platform. Useful for URL templating

URL Templating

The target_websocket_url field supports dynamic values:

{organization_uuid}: Replaced with the organization's UUID
{charge_box_id}: Replaced with the charger's ID in Fulminata
{target_charge_box_id}: Replaced with the target_charge_box_id field, if provided

cURL Example: Enroll with Proxy

# Set your Organization UUID

ORG_UUID="your-actual-org-uuid"

curl -X POST \
  "http://ocpp.voltra.sh/api/v1/organizations/${ORG_UUID}/chargers/enroll-with-proxy?pretty=true" \
  -H "Content-Type: application/json" \
  -H "x-api-key: F956FB45-22D6-421F-BE12-660CD7ED9815" \
  -d '{
    "charge_box_id": "CP-PROX-01",
    "charger_name": "Main Lobby Charger",
    "vendor_name": "Fulminata",
    "model_name": "ProxyCharger",
    "target_platform_identifier": "Main_CSMS",
    "target_websocket_url": "wss://third-party.com/ocpp/{target_charge_box_id}",
    "target_authentication_method": "Basic",
    "target_charge_box_id": "CSMS-ID-555",
    "target_auth_basic_password": "third-party-secret-password"
  }'

Success Response (200 OK)

The response includes the details for both the created charger and its proxy configuration:

{
  "success": true,
  "message": "Charger enrolled and proxy configuration created successfully",
  "charger": {
    "charge_box_id": "CP-PROX-01",
    "ocpp_proxy_url": "ws://ocpp.voltra.sh/your-actual-org-uuid/ocpp_proxy/CP-PROX-01",
    "ocpp_password": "auto-generated-secure-password"
  },
  "proxy_configuration": {
    "id": 123,
    "target_platform_identifier": "Main_CSMS",
    "target_websocket_url": "wss://third-party.com/ocpp/{target_charge_box_id}"
  }
}

CRUD Endpoints for Proxy Configurations

These endpoints provide full CRUD (Create, Read, Update, Delete) functionality for managing existing proxy configurations.

1. List Proxy Configurations

Retrieves all proxy configurations for a given organization.

Endpoint: GET /api/v1/organizations/{organization_uuid}/proxy_configurations

Path Parameters:

organization_uuid (required) - The organization's unique identifier

Authentication: Same options as described above (API Key or Session)

cURL Example:

curl "http://ocpp.voltra.sh/api/v1/organizations/${ORG_UUID}/proxy_configurations?pretty=true" \
  -H "x-api-key: F956FB45-22D6-421F-BE12-660CD7ED9815"

Success Response (200 OK):

{
  "success": true,
  "proxy_configurations": [
    {
      "id": 1,
      "charge_box_id": "CHARGER001",
      "organization_uuid": "9aae4c65-d97f-4bd5-9138-9ed67e8db6b6",
      "target_platform_identifier": "ChargePoint",
      "target_websocket_url": "wss://api.chargepoint.com/ocpp/{charge_box_id}",
      "target_authentication_method": "Basic"
    }
  ]
}

2. Create Proxy Configuration

Creates a new proxy configuration for a specific charger.

Endpoint: POST /api/v1/organizations/{organization_uuid}/proxy_configurations

Path Parameters:

organization_uuid (required) - The organization's unique identifier

Request Body:

{
  "charge_box_id": "CHARGER001",
  "target_platform_identifier": "ChargePoint",
  "target_websocket_url": "wss://api.chargepoint.com/ocpp/{charge_box_id}",
  "target_authentication_method": "Basic",
  "target_auth_basic_password": "secret123"
}

3. Get Specific Proxy Configuration

Retrieves the details of a single proxy configuration by its ID.

Endpoint: GET /api/v1/organizations/{organization_uuid}/proxy_configurations/{id}

Path Parameters:

organization_uuid (required) - The organization's unique identifier
id (required) - The unique ID of the proxy configuration

cURL Example:

# Assume the proxy config ID we want is 123

PROXY_ID=123

curl "http://ocpp.voltra.sh/api/v1/organizations/${ORG_UUID}/proxy_configurations/${PROXY_ID}?pretty=true" \
  -H "x-api-key: F956FB45-22D6-421F-BE12-660CD7ED9815"

4. Update Proxy Configuration

Updates an existing proxy configuration. PUT replaces the entire resource, while PATCH modifies only the provided fields.

Endpoints:

PUT /api/v1/organizations/{organization_uuid}/proxy_configurations/{id}
PATCH /api/v1/organizations/{organization_uuid}/proxy_configurations/{id}

Path Parameters:

organization_uuid (required) - The organization's unique identifier
id (required) - The unique ID of the proxy configuration

Request Body: Same as create, but all fields are optional for PATCH

cURL Example (PATCH - Updates only the target URL):

PROXY_ID=123

curl -X PATCH \
  "http://ocpp.voltra.sh/api/v1/organizations/${ORG_UUID}/proxy_configurations/${PROXY_ID}?pretty=true" \
  -H "Content-Type: application/json" \
  -H "x-api-key: F956FB45-22D6-421F-BE12-660CD7ED9815" \
  -d '{
    "target_websocket_url": "wss://new-third-party.com/ocpp/main"
  }'

5. Delete Proxy Configuration

Deletes a proxy configuration.

Endpoint: DELETE /api/v1/organizations/{organization_uuid}/proxy_configurations/{id}

Path Parameters:

organization_uuid (required) - The organization's unique identifier
id (required) - The unique ID of the proxy configuration

cURL Example:

PROXY_ID=123

curl -X DELETE \
  "http://ocpp.voltra.sh/api/v1/organizations/${ORG_UUID}/proxy_configurations/${PROXY_ID}?pretty=true" \
  -H "x-api-key: F956FB45-22D6-421F-BE12-660CD7ED9815"

Connectors API - Data Streaming

Connectors provide a powerful way to stream your organization's data from the Voltra platform to your own data storage solutions in real-time. This functionality is ideal for building a data lake, performing in-depth analytics, or archiving data for compliance and long-term storage.

At its core, a connector listens for specific data events within our system—currently, all OCPP (Open Charge Point Protocol) proxy logs—and securely pipes this data from our internal message bus (Kafka) to your configured storage provider.

Supported Storage Providers

We currently support the following storage providers:

AWS S3 (aws_s3)
DigitalOcean Spaces (digital_ocean_spaces)
Google Cloud Storage (gcp_storage)
Azure Blob Storage (azure_storage)

Connectors Authentication

Connectors API uses Bearer token authentication instead of API key authentication:

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

Base URL for Connectors

https://ocpp.voltra.sh/api/orgs/<YOUR_ORG_UUID>/connectors

List All Connectors

Retrieves a list of all connector configurations belonging to your organization.

Endpoint: GET /api/orgs/<YOUR_ORG_UUID>/connectors

cURL Example:

curl -X GET \
  "https://ocpp.voltra.sh/api/orgs/<YOUR_ORG_UUID>/connectors" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Success Response (200 OK):

{
  "success": true,
  "connectors": [
    {
      "updated_at": "2023-10-27T10:00:00Z",
      "type": "aws_s3",
      "name": "my-s3-backup",
      "inserted_at": "2023-10-27T10:00:00Z",
      "id": "c7a8b9d0-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
      "enabled": true,
      "credentials": {},
      "configuration": {
        "bucket": "my-ocpp-logs-bucket",
        "region": "us-east-1"
      }
    }
  ],
  "message": "Connector configurations retrieved successfully"
}

Note: For security, the credentials field is always returned as an empty object.

Get a Single Connector

Retrieves the details for a specific connector configuration by its ID.

Endpoint: GET /api/orgs/<YOUR_ORG_UUID>/connectors/<CONNECTOR_ID>

cURL Example:

curl -X GET \
  "https://ocpp.voltra.sh/api/orgs/<YOUR_ORG_UUID>/connectors/<CONNECTOR_ID>" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Success Response (200 OK):

{
  "success": true,
  "connector": {
    "updated_at": "2023-10-27T10:00:00Z",
    "type": "aws_s3",
    "name": "my-s3-backup",
    "inserted_at": "2023-10-27T10:00:00Z",
    "id": "c7a8b9d0-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
    "enabled": true,
    "credentials": {},
    "configuration": {
      "bucket": "my-ocpp-logs-bucket",
      "region": "us-east-1"
    }
  },
  "message": "Connector configuration retrieved successfully"
}

Create a Connector

Creates a new connector configuration, which will start a new data stream to your specified storage provider as soon as it's created.

Endpoint: POST /api/orgs/<YOUR_ORG_UUID>/connectors

Common Body Parameters:

name (string, required): A unique, machine-readable name for your connector. Must contain only lowercase letters, numbers, and dashes (e.g., my-production-backup)
type (string, required): The type of connector. Must be one of the supported provider keys
enabled (boolean, optional, default: true): Set to false to create the connector without activating it immediately
configuration (object, required): Provider-specific configuration details
credentials (object, required): Provider-specific authentication credentials

AWS S3 (`aws_s3`)

cURL Example:

curl -X POST \
  "https://ocpp.voltra.sh/api/orgs/<YOUR_ORG_UUID>/connectors" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-aws-s3-connector",
    "type": "aws_s3",
    "configuration": {
      "bucket": "your-s3-bucket-name",
      "region": "us-east-1"
    },
    "credentials": {
      "access_key_id": "YOUR_AWS_ACCESS_KEY_ID",
      "secret_access_key": "YOUR_AWS_SECRET_ACCESS_KEY"
    }
  }'

DigitalOcean Spaces (`digital_ocean_spaces`)

cURL Example:

curl -X POST \
  "https://ocpp.voltra.sh/api/orgs/<YOUR_ORG_UUID>/connectors" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-do-spaces-connector",
    "type": "digital_ocean_spaces",
    "configuration": {
      "bucket": "your-spaces-name",
      "region": "nyc3"
    },
    "credentials": {
      "access_key_id": "YOUR_SPACES_ACCESS_KEY",
      "secret_access_key": "YOUR_SPACES_SECRET_KEY"
    }
  }'

Google Cloud Storage (`gcp_storage`)

For GCP, you must provide your service account key file's JSON content as a single-line string.

cURL Example:

# On macOS/Linux, prepare the service account JSON by reading it from a file and removing newlines

SA_JSON=$(cat /path/to/your/service-account.json | tr -d '\n')

curl -X POST \
  "https://ocpp.voltra.sh/api/orgs/<YOUR_ORG_UUID>/connectors" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"my-gcp-storage-connector\",
    \"type\": \"gcp_storage\",
    \"configuration\": {
      \"bucket\": \"your-gcs-bucket-name\"
    },
    \"credentials\": {
      \"service_account_json\": \"${SA_JSON}\"
    }
  }"

Azure Blob Storage (`azure_storage`)

cURL Example:

curl -X POST \
  "https://ocpp.voltra.sh/api/orgs/<YOUR_ORG_UUID>/connectors" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-azure-storage-connector",
    "type": "azure_storage",
    "configuration": {
      "storage_account": "your_azure_storage_account_name",
      "container": "your_blob_container_name"
    },
    "credentials": {
      "account_key": "YOUR_AZURE_STORAGE_ACCOUNT_KEY"
    }
  }'

Success Response (201 Created):

{
  "success": true,
  "message": "Connector configuration created successfully"
}

Update a Connector

Updates an existing connector configuration. You can modify its name, enabled status, credentials, or configuration. Any fields provided in the request body will overwrite existing values; omitted fields will remain unchanged.

Endpoint: PUT /api/orgs/<YOUR_ORG_UUID>/connectors/<CONNECTOR_ID>

cURL Example (Disable connector and change name):

curl -X PUT \
  "https://ocpp.voltra.sh/api/orgs/<YOUR_ORG_UUID>/connectors/<CONNECTOR_ID>" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-prod-s3-backup-disabled",
    "enabled": false
  }'

Success Response (200 OK):

{
  "success": true,
  "connector": {
    "updated_at": "2023-10-27T10:05:00Z",
    "type": "aws_s3",
    "name": "my-prod-s3-backup-disabled",
    "inserted_at": "2023-10-27T10:00:00Z",
    "id": "c7a8b9d0-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
    "enabled": false,
    "credentials": {},
    "configuration": {
      "bucket": "my-ocpp-logs-bucket",
      "region": "us-east-1"
    }
  },
  "message": "Connector configuration updated successfully"
}

Delete a Connector

Permanently deletes a connector configuration. This action will immediately stop the associated data stream. This cannot be undone.

Endpoint: DELETE /api/orgs/<YOUR_ORG_UUID>/connectors/<CONNECTOR_ID>

cURL Example:

curl -X DELETE \
  "https://ocpp.voltra.sh/api/orgs/<YOUR_ORG_UUID>/connectors/<CONNECTOR_ID>" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Success Response (200 OK):

{
  "success": true,
  "message": "Connector configuration deleted successfully"
}

About OCPP Proxy​

Authentication Methods​

Combined Endpoint: Enroll Charger & Configure Proxy​

Endpoint​

Field Explanations​

Charger Fields (ChargeBox)​

Proxy Fields (ProxyConfiguration)​

URL Templating​

cURL Example: Enroll with Proxy​

Success Response (200 OK)​

CRUD Endpoints for Proxy Configurations​

1. List Proxy Configurations​

2. Create Proxy Configuration​

3. Get Specific Proxy Configuration​

4. Update Proxy Configuration​

5. Delete Proxy Configuration​

Connectors API - Data Streaming

Supported Storage Providers​

Connectors Authentication​

Base URL for Connectors​

List All Connectors​

Get a Single Connector​

Create a Connector​

AWS S3 (aws_s3)​

DigitalOcean Spaces (digital_ocean_spaces)​

Google Cloud Storage (gcp_storage)​

Azure Blob Storage (azure_storage)​

Update a Connector​

Delete a Connector​

About OCPP Proxy

Authentication Methods

Combined Endpoint: Enroll Charger & Configure Proxy

Endpoint

Field Explanations

Charger Fields (`ChargeBox`)

Proxy Fields (`ProxyConfiguration`)

URL Templating

cURL Example: Enroll with Proxy

Success Response (200 OK)

CRUD Endpoints for Proxy Configurations

1. List Proxy Configurations

2. Create Proxy Configuration

3. Get Specific Proxy Configuration

4. Update Proxy Configuration

5. Delete Proxy Configuration

Supported Storage Providers

Connectors Authentication

Base URL for Connectors

List All Connectors

Get a Single Connector

Create a Connector

AWS S3 (`aws_s3`)

DigitalOcean Spaces (`digital_ocean_spaces`)

Google Cloud Storage (`gcp_storage`)

Azure Blob Storage (`azure_storage`)

Update a Connector

Delete a Connector