# Users & access

> Users in your organisation with their API scopes.

API reference

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:

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

Python:

```python
import ·  httpx

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

TypeScript:

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

Example response · 200

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

Can raise

-   401 · no valid token
-   403 · scope missing
-   429 · rate limited

[ALL CODES →](https://docs.ebx.energy/reference/errors.md)

 · POST · /v1/users

### Create User

users.write

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

Request body · required

email · REQUIRED

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:

```bash
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"]}'
```

Python:

```python
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())
```

TypeScript:

```typescript
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 response · 201

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

Can raise

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

[ALL CODES →](https://docs.ebx.energy/reference/errors.md)· DELETE · /v1/users/{email}

### Delete User

users.write

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

Path parameters

email · REQUIRED

string

Example value

cURL:

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

Python:

```python
import ·  httpx

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

TypeScript:

```typescript
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

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

[ALL CODES →](https://docs.ebx.energy/reference/errors.md)

· PUT · /v1/users/{email}/scopes

### Update User Scopes

users.write

Replace a user's scopes with the provided set.

Path parameters

email · REQUIRED

string

Request body · required

scopes · REQUIRED

array\[enum\] · Desired set of scopes (replaces current scopes)

Example value

cURL:

```bash
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"]}'
```

Python:

```python
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())
```

TypeScript:

```typescript
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 response · 200

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

Can raise

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

[ALL CODES →](https://docs.ebx.energy/reference/errors.md)

· GET · /v1/users/me

### Get Current User Info

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

This endpoint takes no parameters.

Example value

cURL:

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

Python:

```python
import ·  httpx

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

TypeScript:

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

Example response · 200

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

Can raise

-   429 · rate limited

[ALL CODES →](https://docs.ebx.energy/reference/errors.md)

· 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:

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

Python:

```python
import ·  httpx

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

TypeScript:

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

Example response · 200

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

Can raise

-   429 · rate limited

[ALL CODES →](https://docs.ebx.energy/reference/errors.md)

· 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

enum · `en` · `de`

theme

enum · `light` · `dark`

Example value

cURL:

```bash
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"}'
```

Python:

```python
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())
```

TypeScript:

```typescript
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 response · 200

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

Can raise

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

[ALL CODES →](https://docs.ebx.energy/reference/errors.md)