# 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.

API reference

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.

6 endpoints

· GET · /v1/integrations

### List Integrations

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:

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

Python:

```python
import ·  httpx

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

TypeScript:

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

Example response · 200

```json
[ · 
   · { · 
     · "integration_id" · : ·   · "<string>" · , · 
     · "name" · : ·   · "<string>" · , · 
     · "organization_id" · : ·   · "<string>" · , · 
     · "created_at" · : ·   · "<string>" · 
   · } · 
 · ]
```

Can raise

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

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

 · POST · /v1/integrations

### Create Integration

clients.write

Create a Cognito app client for M2M integration access.

The integration name must be unique within your organization. The internal Cognito client will be named with a format that prevents collisions.

Request body · required

name · REQUIRED

string · User-facing display name for the integration (must be unique within your organization)

scopes · REQUIRED

array\[enum\] · OAuth scopes to grant this integration. Available scopes for M2M integrations: "asset.read", "asset.write", "alarm.read", "alarm.write", "market.read", "market.write", "report.read", "users.read", "users.write", "clients.read", "clients.write". You can only grant scopes you possess. Internal scopes (pool, dispatch, tso) are not grantable.

Example value

cURL:

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

Python:

```python
import ·  httpx

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

TypeScript:

```typescript
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" · ]} · ) · , · 
 · } · );
 · const ·  data =  · await ·  res.json();
```

Example response · 201

```json
{ · 
   · "integration_id" · : ·   · "<string>" · , · 
   · "client_secret" · : ·   · "<string>" · , · 
   · "name" · : ·   · "<string>" · , · 
   · "organization_id" · : ·   · "<string>" · , · 
   · "scopes" · : ·   · [ · 
     · "<string>" · 
   · ] · 
 · }
```

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/integrations/{integration\_id}

### Delete Integration

clients.write

Delete an M2M integration.

Path parameters

integration\_id · REQUIRED

string

Example value

cURL:

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

Python:

```python
import ·  httpx

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

TypeScript:

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

-   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)

· GET · /v1/integrations/{integration\_id}/secrets

### List Secrets

clients.read

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

Path parameters

integration\_id · REQUIRED

string

Example value

cURL:

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

Python:

```python
import ·  httpx

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

TypeScript:

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

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

Can raise

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

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

· POST · /v1/integrations/{integration\_id}/secrets

### Add Secret

clients.write

Add a new secret to an M2M integration.

Cognito supports up to two active secrets per integration. To complete a rotation: add a new secret, migrate consumers, then delete the old one.

Path parameters

integration\_id · REQUIRED

string

Example value

cURL:

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

Python:

```python
import ·  httpx

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

TypeScript:

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

```json
{ · 
   · "integration_id" · : ·   · "<string>" · , · 
   · "secret_id" · : ·   · "<string>" · , · 
   · "secret_value" · : ·   · "<string>" · 
 · }
```

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)

· DELETE · /v1/integrations/{integration\_id}/secrets/{secret\_id}

### Delete Secret

clients.write

Delete a specific secret from an M2M integration.

Path parameters

integration\_id · REQUIRED

string

secret\_id · REQUIRED

string

Example value

cURL:

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

Python:

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

TypeScript:

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

-   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)