API reference

Users & access

Users in your organisation with their API scopes.

7 endpoints

GET/v1/users

List Users

users.read

List Cognito users in the caller's organization with their API scopes.

This endpoint takes no parameters.

Example value

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

import httpx

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

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

Example response200

{
  "users": [
    {
      "email": "<string>",
      "scopes": [
        "asset.read"
      ],
      "status": "<string>",
      "enabled": false,
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}

Can raise

401no valid token
403scope missing
429rate limited

ALL CODES →

POST/v1/users

Create User

users.write

Create a new Cognito user in the caller's organization.

Request body · required

emailREQUIRED: string<email>Email address (also used as Cognito username); normalized to lowercase
scopes: array[enum]API scopes to grant (e.g. ["asset.read", "dispatch.write"])

Example value

curl -X POST "https://api.ebx.energy/v1/users" \
  -H "Authorization: Bearer $EBX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"name@example.com","scopes":["asset.read"]}'

import httpx

r = httpx.post(
    "https://api.ebx.energy/v1/users",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "email": "name@example.com",
        "scopes": [
            "asset.read",
        ],
    },
)
print(r.json())

const res = await fetch("https://api.ebx.energy/v1/users", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"email":"name@example.com","scopes":["asset.read"]}),
});
const data = await res.json();

Example response201

{
  "email": "<string>",
  "organization_id": "<string>",
  "scopes": [
    "asset.read"
  ]
}

Can raise

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

ALL CODES →

DELETE/v1/users/{email}

Delete User

users.write

Hard-delete a Cognito user who belongs to the caller's organization.

Path parameters

emailREQUIRED: string

Example value

curl -X DELETE "https://api.ebx.energy/v1/users/ops@yourcompany.com" \
  -H "Authorization: Bearer $EBX_TOKEN"

import httpx

r = httpx.delete(
    "https://api.ebx.energy/v1/users/ops@yourcompany.com",
    headers={"Authorization": f"Bearer {token}"},
)
print(r.status_code)

const res = await fetch("https://api.ebx.energy/v1/users/ops@yourcompany.com", {
  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 →

PUT/v1/users/{email}/scopes

Update User Scopes

users.write

Replace a user's scopes with the provided set.

Path parameters

emailREQUIRED: string

Request body · required

scopesREQUIRED: array[enum]Desired set of scopes (replaces current scopes)

Example value

curl -X PUT "https://api.ebx.energy/v1/users/ops@yourcompany.com/scopes" \
  -H "Authorization: Bearer $EBX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scopes":["asset.read"]}'

import httpx

r = httpx.put(
    "https://api.ebx.energy/v1/users/ops@yourcompany.com/scopes",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "scopes": [
            "asset.read",
        ],
    },
)
print(r.json())

const res = await fetch("https://api.ebx.energy/v1/users/ops@yourcompany.com/scopes", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"scopes":["asset.read"]}),
});
const data = await res.json();

Example response200

{
  "email": "<string>",
  "scopes": [
    "asset.read"
  ],
  "added": [
    "asset.read"
  ],
  "removed": [
    "asset.read"
  ]
}

Can raise

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

ALL CODES →

GET/v1/users/me

Get Current User Info

Return the authenticated caller's identity (org, scopes).

This endpoint takes no parameters.

Example value

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

import httpx

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

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

Example response200

{
  "user_id": "<string>",
  "email": "<string>",
  "organization_id": "<string>",
  "scopes": [
    "asset.read"
  ],
  "is_m2m": false
}

Can raise

429rate limited

ALL CODES →

GET/v1/users/me/preferences

Get Current User Preferences

Return the caller's account defaults (language, appearance); all null until first saved.

This endpoint takes no parameters.

Example value

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

import httpx

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

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

Example response200

{
  "user_id": "<string>",
  "locale": "en",
  "theme": "light",
  "updated_at": "2026-01-01T00:00:00Z"
}

Can raise

429rate limited

ALL CODES →

PUT/v1/users/me/preferences

Update Current User Preferences

Replace the caller's account defaults; the portal applies them on every device the caller signs in on.

Request body · required

locale: enumende
theme: enumlightdark

Example value

curl -X PUT "https://api.ebx.energy/v1/users/me/preferences" \
  -H "Authorization: Bearer $EBX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"locale":"en","theme":"light"}'

import httpx

r = httpx.put(
    "https://api.ebx.energy/v1/users/me/preferences",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "locale": "en",
        "theme": "light",
    },
)
print(r.json())

const res = await fetch("https://api.ebx.energy/v1/users/me/preferences", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"locale":"en","theme":"light"}),
});
const data = await res.json();

Example response200

{
  "user_id": "<string>",
  "locale": "en",
  "theme": "light",
  "updated_at": "2026-01-01T00:00:00Z"
}

Can raise

400malformed request
409state conflict
422validation failed
429rate limited

ALL CODES →