API reference

Integrations

Machine to machine integrations in your organisation and their secrets. Up to two secrets can be active per integration, so they can be rotated without downtime.

7 endpoints

GET/v1/integrations

List Integrations

clients.read

Required scopes: clients.read

List M2M integrations visible to the caller.

ebx admins get all integrations across all organisations; other users are scoped to their own organisation(s).

This endpoint takes no parameters.

Example value

curl "https://api.ebx.energy/v1/integrations" \
  -H "Authorization: Bearer $EBX_TOKEN"

import httpx

r = httpx.get(
    "https://api.ebx.energy/v1/integrations",
    headers={"Authorization": f"Bearer {token}"},
)
print(r.json())

const res = await fetch("https://api.ebx.energy/v1/integrations", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
const data = await res.json();

Example response200

[
  {
    "integration_id": "<string>",
    "name": "<string>",
    "organization_id": "<string>",
    "created_at": "<string>",
    "asset_ids": [
      "<string>"
    ]
  }
]

Can raise

401no valid token
403scope missing
429rate limited

ALL CODES →

POST/v1/integrations

Create Integration

clients.write

Required scopes: clients.write

Create an M2M integration for API access.

The integration name must be unique within your organization.

Pass asset_ids to restrict the integration to some of your organization's assets, e.g. to give a partner read access to a single asset. A restricted integration may only hold the asset.read scope.

Request body · required

nameREQUIRED: stringUser-facing display name for the integration (must be unique within your organization)
scopesREQUIRED: array[enum]OAuth scopes to grant this integration. Available scopes for M2M integrations: "asset.read", "asset.write", "alarm.read", "alarm.write", "dispatch.read", "dispatch.write", "onboarding.read", "market.read", "market.write", "report.read", "invoice.read", "users.read", "users.write", "clients.read", "clients.write", "restrictions.review", "restrictions.approve", "restrictions.write_direct". You can only grant scopes you possess. EBX administrators may additionally grant "onboarding.write". Internal scopes (pool, tso, inventory, onboarding tasks) are not grantable.
asset_ids: array[string]Restrict the integration to these assets of your organization, e.g. to give a partner access to a single asset. An asset-restricted integration is read-only: its scopes must be exactly ["asset.read"]. Omit to give the integration access to every asset of your organization.

Example value

curl -X POST "https://api.ebx.energy/v1/integrations" \
  -H "Authorization: Bearer $EBX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"<string>","scopes":["asset.read"],"asset_ids":["asset-123"]}'

import httpx

r = httpx.post(
    "https://api.ebx.energy/v1/integrations",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "name": "<string>",
        "scopes": [
            "asset.read",
        ],
        "asset_ids": [
            "asset-123",
        ],
    },
)
print(r.json())

const res = await fetch("https://api.ebx.energy/v1/integrations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"name":"<string>","scopes":["asset.read"],"asset_ids":["asset-123"]}),
});
const data = await res.json();

Example response201

{
  "integration_id": "<string>",
  "client_secret": "<string>",
  "name": "<string>",
  "organization_id": "<string>",
  "scopes": [
    "<string>"
  ],
  "asset_ids": [
    "<string>"
  ]
}

Can raise

400malformed request
401no valid token
403scope missing
409state conflict
422validation failed
429rate limited

ALL CODES →

GET/v1/integrations/{integration_id}

Get Integration

clients.read

Required scopes: clients.read

Get an M2M integration, including the scopes it may request.

Path parameters

integration_idREQUIRED: string

Example value

curl "https://api.ebx.energy/v1/integrations/scada-primary" \
  -H "Authorization: Bearer $EBX_TOKEN"

import httpx

r = httpx.get(
    "https://api.ebx.energy/v1/integrations/scada-primary",
    headers={"Authorization": f"Bearer {token}"},
)
print(r.json())

const res = await fetch("https://api.ebx.energy/v1/integrations/scada-primary", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
const data = await res.json();

Example response200

{
  "integration_id": "<string>",
  "name": "<string>",
  "organization_id": "<string>",
  "created_at": "<string>",
  "asset_ids": [
    "<string>"
  ],
  "scopes": [
    "<string>"
  ]
}

Can raise

401no valid token
403scope missing
404unknown or not visible
429rate limited

ALL CODES →

DELETE/v1/integrations/{integration_id}

Delete Integration

clients.write

Required scopes: clients.write

Delete an M2M integration.

Path parameters

integration_idREQUIRED: string

Example value

curl -X DELETE "https://api.ebx.energy/v1/integrations/scada-primary" \
  -H "Authorization: Bearer $EBX_TOKEN"

import httpx

r = httpx.delete(
    "https://api.ebx.energy/v1/integrations/scada-primary",
    headers={"Authorization": f"Bearer {token}"},
)
print(r.status_code)

const res = await fetch("https://api.ebx.energy/v1/integrations/scada-primary", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

Returns 204 with no body.

Can raise

400malformed request
401no valid token
403scope missing
404unknown or not visible
409state conflict
429rate limited

ALL CODES →

GET/v1/integrations/{integration_id}/secrets

List Secrets

clients.read

Required scopes: clients.read

List secret descriptors for an M2M integration (values are never returned).

Path parameters

integration_idREQUIRED: string

Example value

curl "https://api.ebx.energy/v1/integrations/scada-primary/secrets" \
  -H "Authorization: Bearer $EBX_TOKEN"

import httpx

r = httpx.get(
    "https://api.ebx.energy/v1/integrations/scada-primary/secrets",
    headers={"Authorization": f"Bearer {token}"},
)
print(r.json())

const res = await fetch("https://api.ebx.energy/v1/integrations/scada-primary/secrets", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
const data = await res.json();

Example response200

[
  {
    "secret_id": "<string>",
    "creation_date": "<string>"
  }
]

Can raise

401no valid token
403scope missing
404unknown or not visible
429rate limited

ALL CODES →

POST/v1/integrations/{integration_id}/secrets

Add Secret

clients.write

Required scopes: clients.write

Add a new secret to an M2M integration.

Each integration supports up to two active secrets. To rotate a secret, add a new one, update your applications to use it, then delete the old one.

Path parameters

integration_idREQUIRED: string

Example value

curl -X POST "https://api.ebx.energy/v1/integrations/scada-primary/secrets" \
  -H "Authorization: Bearer $EBX_TOKEN"

import httpx

r = httpx.post(
    "https://api.ebx.energy/v1/integrations/scada-primary/secrets",
    headers={"Authorization": f"Bearer {token}"},
)
print(r.json())

const res = await fetch("https://api.ebx.energy/v1/integrations/scada-primary/secrets", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
const data = await res.json();

Example response201

{
  "integration_id": "<string>",
  "secret_id": "<string>",
  "secret_value": "<string>"
}

Can raise

400malformed request
401no valid token
403scope missing
404unknown or not visible
409state conflict
429rate limited

ALL CODES →

DELETE/v1/integrations/{integration_id}/secrets/{secret_id}

Delete Secret

clients.write

Required scopes: clients.write

Delete a specific secret from an M2M integration.

Path parameters

integration_idREQUIRED: string
secret_idREQUIRED: string

Example value

curl -X DELETE "https://api.ebx.energy/v1/integrations/scada-primary/secrets/scada-primary-basic-auth" \
  -H "Authorization: Bearer $EBX_TOKEN"

import httpx

r = httpx.delete(
    "https://api.ebx.energy/v1/integrations/scada-primary/secrets/scada-primary-basic-auth",
    headers={"Authorization": f"Bearer {token}"},
)
print(r.status_code)

const res = await fetch("https://api.ebx.energy/v1/integrations/scada-primary/secrets/scada-primary-basic-auth", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

Returns 204 with no body.

Can raise

400malformed request
401no valid token
403scope missing
404unknown or not visible
409state conflict
429rate limited

ALL CODES →